Covering some parts of the cogutil in doxydocs; reformatted cluster.h…

… & .c to make description visible to doxygen

doc/doxydoc/libcogutil.dox

@@ -1,3 +1,4 @@
+namespace opencog {
 /**
 
 \page libcogutil cogutil library
@@ -8,7 +9,30 @@ found no place elsewhere. To build it use:
 make cogutil
 @endcode
 
+\section sect_files Files
 
+\subsection ssect_algorithm_h algorithm.h
+Hosts small templated functions like for_each(),
+accumulate2d(), etc. Sets utilities are also present.
+
+\subsection ssect_ansi ansi (.h & .cc)
+ANSI codes for colored output in terminals that support this feature.
+Instead of directly using the codes, make use of the ansi_code()
+function that checks the \b ANSI_ENABLED configuration variable
+and either appends the code or an empty string.
+
+\subsection ssect_basedvar based_variant.h
+Defines a simple variant with base; seems to be used only in defining
+moses::disc_knob type.
+
+\section sect_libs Libraries
+
+\subsection ssect_clustering The C Clustering Library
+This library (version 1.49) was written at the Laboratory of DNA Information Analysis,
+Human Genome Center, Institute of Medical Science, University of Tokyo
+by Michiel Jan Laurens de Hoon.
+
+Methods such as clusterdistance(), getclustercentroids(), kcluster() are provided.
 
 \if MARKER_TREE_START
 ignored by doxygen; used as markers for update-links.py;
@@ -23,4 +47,4 @@ ignored by doxygen; used as markers for update-links.py;
 ignored by doxygen; used as markers for update-links.py;
 \endif
 */
-
+} //~namespace opencog

doc/doxydoc/progcogserver.dox

@@ -1,7 +1,11 @@
 /**
-
 \page progcogserver cogserver program
 
+To build it use:
+@code
+make cogserver
+@endcode
+
 \if MARKER_TREE_START
 ignored by doxygen; used as markers for update-links.py;
 \endif

doc/doxygen.conf.in

@@ -251,7 +251,7 @@ IDL_PROPERTY_SUPPORT   = YES
 # member in the group (if any) for the other members of the group. By default 
 # all members of a group must be documented explicitly.
 
-DISTRIBUTE_GROUP_DOC   = NO
+DISTRIBUTE_GROUP_DOC   = YES
 
 # Set the SUBGROUPING tag to YES (the default) to allow class member groups of 
 # the same type (for instance a group of public functions) to be put as a 

opencog/util/algorithm.h

@@ -13,29 +13,31 @@
 namespace opencog
 {
 
-//these needs to be changed for non-gcc
+/// @todo these needs to be changed for non-gcc
 using __gnu_cxx::copy_n;
 using __gnu_cxx::lexicographical_compare_3way;
 using __gnu_cxx::random_sample_n;
 using __gnu_cxx::random_sample;
 using __gnu_cxx::is_heap;
 using __gnu_cxx::is_sorted;
 
-//binary and ternary and quaternary for_each
+//! binary for_each
 template<typename It1, typename It2, typename F>
 F for_each(It1 from1, It1 to1, It2 from2, F f)
 {
     for (;from1 != to1;++from1, ++from2)
         f(*from1, *from2);
     return f;
 }
+//! ternary for_each
 template<typename It1, typename It2, typename It3, typename F>
 F for_each(It1 from1, It1 to1, It2 from2, It3 from3, F f)
 {
     for (;from1 != to1;++from1, ++from2, ++from3)
         f(*from1, *from2, *from3);
     return f;
 }
+//! quaternary for_each
 template<typename It1, typename It2, typename It3, typename It4, typename F>
 F for_each(It1 from1, It1 to1, It2 from2, It3 from3, It4 from4, F f)
 {
@@ -44,7 +46,7 @@ F for_each(It1 from1, It1 to1, It2 from2, It3 from3, It4 from4, F f)
     return f;
 }
 
-//accumulate over a range of containers
+//! accumulate over a range of containers
 template <class iter, class T>
 T accumulate2d(iter first, iter last, T init)
 {
@@ -53,14 +55,14 @@ T accumulate2d(iter first, iter last, T init)
     return init;
 }
 
-// appends b at the end of a, that is a = a@b
+//! appends b at the end of a, that is a = a@b
 template<class T>
 void append(T& a, const T& b) {
     a.insert(a.end(), b.begin(), b.end());
 }
 
-//erase the intersection of sorted ranges [from1,to1) and [from2,to2) from c,
-//leaving the difference
+//! erase the intersection of sorted ranges [from1,to1) and [from2,to2) from c,
+//! leaving the difference
 template<typename Erase, typename It1, typename It2, typename Comp>
 void erase_set_intersection(Erase erase, It1 from1, It1 to1,
                             It2 from2, It2 to2, Comp comp)
@@ -81,8 +83,8 @@ void erase_set_intersection(Erase erase, It1 from1, It1 to1,
         }
 }
 
-//erase the difference of sorted ranges [from1,to1) and [from2,to2) from c,
-//leaving the intersection
+//! erase the difference of sorted ranges [from1,to1) and [from2,to2) from c,
+//! leaving the intersection
 template<typename Erase, typename It1, typename It2, typename Comp>
 void erase_set_difference(Erase erase, It1 from1, It1 to1,
                           It2 from2, It2 to2, Comp comp)
@@ -105,9 +107,9 @@ void erase_set_difference(Erase erase, It1 from1, It1 to1,
         erase(from1++);
 }
 
-//insert [from2,to2)-[from1,to1) with inserter
-//i.e., if insert inserts into the container holding [from1,to1),
-//it will now hold the union
+//! insert [from2,to2)-[from1,to1) with inserter
+//! i.e., if insert inserts into the container holding [from1,to1),
+//! it will now hold the union
 template<typename Insert, typename It1, typename It2, typename Comp>
 void insert_set_complement(Insert insert, It1 from1, It1 to1,
                            It2 from2, It2 to2, Comp comp)
@@ -133,6 +135,7 @@ void insert_set_complement(Insert insert, It1 from1, It1 to1,
     }
 }
 
+//! determine if the intersection of two sets is the empty set
 template<typename It1, typename It2, typename Comp>
 bool has_empty_intersection(It1 from1, It1 to1,
                             It2 from2, It2 to2, Comp comp)
@@ -152,6 +155,7 @@ bool has_empty_intersection(It1 from1, It1 to1,
     return true;
 }
 
+//! determine if the intersection of two sets is the empty set
 template<typename Set>
 bool has_empty_intersection(const Set& ls, const Set& rs) {
     return has_empty_intersection(ls.begin(), ls.end(),
@@ -192,7 +196,7 @@ bool is_disjoint(const Set1 &set1, const Set2 &set2)
 }
 
 /**
- * return a singleton set with the input given in it
+ * \return a singleton set with the input given in it
  */
 template<typename Set>
 Set make_singleton_set(const typename Set::value_type& v) {
@@ -202,7 +206,7 @@ Set make_singleton_set(const typename Set::value_type& v) {
 }
 
 /**
- * Return s1 union s2
+ * \return s1 union s2
  * s1 and s2 being std::set or similar concept
  */
 template<typename Set>
@@ -213,7 +217,7 @@ Set set_union(const Set& s1, const Set& s2) {
 }
 
 /**
- * Return s1 inter s2
+ * \return s1 inter s2
  * s1 and s2 must be sorted
  */
 template<typename Set>
@@ -225,7 +229,7 @@ Set set_intersection(const Set& s1, const Set& s2) {
 }
 
 /**
- * Returns s1 - s2
+ * \return s1 - s2
  * s1 and s2 must be sorted
  */
 template<typename Set>
@@ -236,8 +240,8 @@ Set set_difference(const Set& s1, const Set& s2) {
     return res;
 }
 
-// Predicate maps to the range [0, n)
-// n-1 values (the pivots) are copied to out
+//! Predicate maps to the range [0, n)
+//! n-1 values (the pivots) are copied to out
 template<typename It, typename Pred, typename Out>
 Out n_way_partition(It begin, It end, const Pred p, int n, Out out)
 {
@@ -248,16 +252,13 @@ Out n_way_partition(It begin, It end, const Pred p, int n, Out out)
 }
 
 /**
- * return the power set ps of s such that all elements of ps are
+ * \return the power set ps of s such that all elements of ps are
  * subsets of size n or below.
  *
  * @param s       the input set
- *
  * @param n       the size of the largest subset of s. If n is larger than
  *                |s| then the size of the largest subset of s will be |s|
- *
  * @param exact   if true then do not include subsets of size below n
- *
  * @return        the power set of s with subsets up to size n
  */
 template<typename Set> std::set<Set> powerset(const Set& s, size_t n,
@@ -280,8 +281,9 @@ template<typename Set> std::set<Set> powerset(const Set& s, size_t n,
         res.insert(Set());
     return res;
 }
+
 /**
- * return the power set of s.
+ * \return the power set of s.
  */
 template<typename Set> std::set<Set> powerset(const Set& s)
 {
@@ -302,7 +304,7 @@ Seq seq_filtered(const Seq& seq, const Indices& indices) {
         res.push_back(seq[idx]);
     return res;
 }
- 
+
 
 } //~namespace opencog
 

opencog/util/ansi.h

@@ -26,6 +26,8 @@
 #include <opencog/util/Config.h>
 namespace opencog {
 
+//!@{
+//! color codes in ANSI
 static const char* const COLOR_OFF = "\033[0m";
 static const char* const BRIGHT = "\033[1m";
 static const char* const RED = "\033[31m";
@@ -35,11 +37,15 @@ static const char* const BLUE = "\033[34m";
 static const char* const MAGENTA = "\033[35m";
 static const char* const CYAN = "\033[36m";
 static const char* const WHITE = "\033[37m";
-
+//!@}
+
+//! inserts the code only if \b ANSI_ENABLED variable is set
 inline void ansi_code(std::string &s,const std::string &code) {
     if (config().get_bool("ANSI_ENABLED")) s.append(code);
 }
 
+//!@{
+//! appends the code if \b ANSI_ENABLED variable is set
 inline void ansi_off(std::string &s) { ansi_code(s,COLOR_OFF); }
 inline void ansi_bright(std::string &s) { ansi_code(s,BRIGHT); }
 inline void ansi_red(std::string &s) { ansi_code(s,RED); }
@@ -49,5 +55,6 @@ inline void ansi_blue(std::string &s) { ansi_code(s,BLUE); }
 inline void ansi_magenta(std::string &s) { ansi_code(s,MAGENTA); }
 inline void ansi_cyan(std::string &s) { ansi_code(s,CYAN); }
 inline void ansi_white(std::string &s) { ansi_code(s,WHITE); }
+//!@}
 
 }