Documentation and creation of Doxygen module "base"

gtsam/base/BTree.h

@@ -10,10 +10,11 @@
  * -------------------------------------------------------------------------- */
 
 /**
- *  Created on: Feb 3, 2010
+ * @file BTree.h
- *  @brief: purely functional binary tree
+ * @brief purely functional binary tree
  * @author Chris Beall
  * @author Frank Dellaert
+ * @date Feb 3, 2010
  */
 
 #include <stack>
@@ -25,6 +26,7 @@ namespace gtsam {
 
 	/**
 	 * @brief Binary tree
+	 * @ingroup base
 	 */
 	template<class KEY, class VALUE>
 	class BTree {
@@ -36,7 +38,7 @@ namespace gtsam {
 	private:
 
 		/**
-		 *  @brief Node in a tree
+		 * Node in a tree
 		 */
 		struct Node {
 
@@ -49,7 +51,8 @@ namespace gtsam {
 			}
 
 			/**
-			 * leaf node with height 1
+			 * Create leaf node with height 1
+			 * @param keyValue (key,value) pair
 			 */
 			Node(const value_type& keyValue) :
 				height_(1), keyValue_(keyValue) {

gtsam/base/DSF.h

@@ -10,14 +10,10 @@
  * -------------------------------------------------------------------------- */
 
 /**
- * DSF.h
+ * @file DSF.h
- *
+ * @date Mar 26, 2010
- *  Created on: Mar 26, 2010
+ * @author Kai Ni
- *  @Author Kai Ni
  * @brief An implementation of Disjoint set forests (see CLR page 446 and up)
- *  						 Quoting from CLR: A disjoint-set data structure maintains a collection
- * 							 S = {S_1,S_2,...} of disjoint dynamic sets. Each set is identified by
- * 							 a representative, which is some member of the set.
  */
 
 #pragma once
@@ -31,6 +27,15 @@
 
 namespace gtsam {
 
+	/**
+	 * Disjoint Set Forest class
+	 *
+	 * Quoting from CLR: A disjoint-set data structure maintains a collection
+	 * S = {S_1,S_2,...} of disjoint dynamic sets. Each set is identified by
+	 * a representative, which is some member of the set.
+	 *
+	 * @ingroup base
+	 */
 	template <class KEY>
 	class DSF : protected BTree<KEY, KEY> {
 

gtsam/base/DSFVector.cpp

@@ -9,13 +9,11 @@
 
  * -------------------------------------------------------------------------- */
 
-/*
+/**
- * DSFVector.cpp
+ * @file DSFVector.cpp
- *
+ * @date Jun 25, 2010
- *   Created on: Jun 25, 2010
+ * @author Kai Ni
- *       Author: nikai
+ * @brief a faster implementation for DSF, which uses vector rather than btree.
- *  Description: a faster implementation for DSF, which uses vector rather than btree.
- *               As a result, the size of the forest is prefixed.
  */
 
 #include <boost/make_shared.hpp>

gtsam/base/DSFVector.h

@@ -9,13 +9,11 @@
 
  * -------------------------------------------------------------------------- */
 
-/*
+/**
- * DSFVector.h
+ * @file DSFVector.h
- *
+ * @date Jun 25, 2010
- * Created on: Jun 25, 2010
+ * @author Kai Ni
- * @Author nikai
+ * @brief A faster implementation for DSF, which uses vector rather than btree. As a result, the size of the forest is prefixed.
- * @brief a faster implementation for DSF, which uses vector rather than btree.
- * As a result, the size of the forest is prefixed.
  */
 
 #pragma once
@@ -28,28 +26,30 @@
 namespace gtsam {
 
 	/**
-	 * A fast impelementation of disjoint set forests that uses vector as underly data structure.
+	 * A fast implementation of disjoint set forests that uses vector as underly data structure.
+	 * @ingroup base
 	 */
 	class DSFVector {
 
 	public:
-		typedef std::vector<size_t> V;
+		typedef std::vector<size_t> V; ///< Vector of ints
-		typedef size_t Label;
+		typedef size_t Label;          ///< Label type
-		typedef std::vector<size_t>::const_iterator const_iterator;
+		typedef V::const_iterator const_iterator; ///< const iterator over V
-		typedef std::vector<size_t>::iterator iterator;
+		typedef V::iterator iterator;///< iterator over V
 
 	private:
-		boost::shared_ptr<V> v_; // could use existing memory to improve the efficiency
+		 // TODO could use existing memory to improve the efficiency
+		boost::shared_ptr<V> v_;
 		std::vector<size_t> keys_;
 
 	public:
-		// constructor that allocate a new memory
+		/// constructor that allocate a new memory
 		DSFVector(const size_t numNodes);
 
-		// constructor that uses the existing memory
+		/// constructor that uses the existing memory
 		DSFVector(const boost::shared_ptr<V>& v_in, const std::vector<size_t>& keys);
 
-		// find the label of the set in which {key} lives
+		/// find the label of the set in which {key} lives
 		inline Label findSet(size_t key) const {
 			size_t parent = (*v_)[key];
 			while (parent != key) {
@@ -59,17 +59,19 @@ namespace gtsam {
 			return parent;
 		}
 
-		// find whether there is one and only one occurrence for the given {label}
+		/// find whether there is one and only one occurrence for the given {label}
 		bool isSingleton(const Label& label) const;
 
-		// get the nodes in the tree with the given label
+		/// get the nodes in the tree with the given label
 		std::set<size_t> set(const Label& label) const;
 
-		// return all sets, i.e. a partition of all elements
+		/// return all sets, i.e. a partition of all elements
 		std::map<Label, std::set<size_t> > sets() const;
+
+		/// return all sets, i.e. a partition of all elements
 		std::map<Label, std::vector<size_t> > arrays() const;
 
-		// the in-place version of makeUnion
+		/// the in-place version of makeUnion
 		void makeUnionInPlace(const size_t& i1, const size_t& i2);
 
 	};

gtsam/base/FastList.h

@@ -13,7 +13,7 @@
  * @file    FastList.h
  * @brief   A thin wrapper around std::list that uses boost's fast_pool_allocator.
  * @author  Richard Roberts
- * @created Oct 22, 2010
+ * @date    Oct 22, 2010
  */
 
 #pragma once
@@ -29,6 +29,7 @@ namespace gtsam {
  * convenience to avoid having lengthy types in the code.  Through timing,
  * we've seen that the fast_pool_allocator can lead to speedups of several
  * percent.
+	 * @ingroup base
  */
 template<typename VALUE>
 class FastList: public std::list<VALUE, boost::fast_pool_allocator<VALUE> > {

gtsam/base/FastMap.h

@@ -13,7 +13,7 @@
  * @file    FastMap.h
  * @brief   A thin wrapper around std::map that uses boost's fast_pool_allocator.
  * @author  Richard Roberts
- * @created Oct 17, 2010
+ * @date    Oct 17, 2010
  */
 
 #pragma once
@@ -30,8 +30,8 @@ namespace gtsam {
  * convenience to avoid having lengthy types in the code.  Through timing,
  * we've seen that the fast_pool_allocator can lead to speedups of several
  * percent.
+ * @ingroup base
  */
-
 template<typename KEY, typename VALUE>
 class FastMap : public std::map<KEY, VALUE, std::less<KEY>, boost::fast_pool_allocator<std::pair<const KEY, VALUE> > > {
 

gtsam/base/FastSet.h

@@ -13,7 +13,7 @@
  * @file    FastSet.h
  * @brief   A thin wrapper around std::set that uses boost's fast_pool_allocator.
  * @author  Richard Roberts
- * @created Oct 17, 2010
+ * @date    Oct 17, 2010
  */
 
 #pragma once
@@ -27,8 +27,8 @@ namespace gtsam {
  * FastSet is a thin wrapper around std::set that uses the boost
  * fast_pool_allocator instead of the default STL allocator.  This is just a
  * convenience to avoid having lengthy types in the code.  Through timing,
- * we've seen that the fast_pool_allocator can lead to speedups of several
+ * we've seen that the fast_pool_allocator can lead to speedups of several %.
- * percent.
+ * @ingroup base
  */
 template<typename VALUE>
 class FastSet : public std::set<VALUE, std::less<VALUE>, boost::fast_pool_allocator<VALUE> > {

gtsam/base/FastVector.h

@@ -10,10 +10,10 @@
  * -------------------------------------------------------------------------- */
 
 /**
- * @file    FastSet.h
+ * @file    FastVector.h
  * @brief   A thin wrapper around std::vector that uses boost's pool_allocator.
  * @author  Richard Roberts
- * @created Feb 9, 2011
+ * @date    Feb 9, 2011
  */
 
 #pragma once
@@ -27,8 +27,8 @@ namespace gtsam {
  * FastVector is a thin wrapper around std::vector that uses the boost
  * pool_allocator instead of the default STL allocator.  This is just a
  * convenience to avoid having lengthy types in the code.  Through timing,
- * we've seen that the pool_allocator can lead to speedups of several
+ * we've seen that the pool_allocator can lead to speedups of several %
- * percent.
+ * @ingroup base
  */
 template<typename VALUE>
 class FastVector: public std::vector<VALUE, boost::pool_allocator<VALUE> > {

gtsam/base/Lie-inl.h

@@ -9,11 +9,11 @@
 
  * -------------------------------------------------------------------------- */
 
-/*
+/**
- * LieBaseImplementations.h
+ * @file Lie-inl.h
- *
+ * @date Jan 9, 2010
- *  Created on: Jan 9, 2010
+ * @author Richard Roberts
- *      Author: richard
+ * @brief Instantiate macro for Lie type
  */
 
 #pragma once

gtsam/base/Testable.h

@@ -10,7 +10,7 @@
  * -------------------------------------------------------------------------- */
 
 /**
- * @file    Testable
+ * @file    Testable.h
  * @brief   Abstract base class for values that can be used in unit tests
  * @author  Frank Dellaert
  * 
@@ -44,6 +44,7 @@ namespace gtsam {
    * The Testable class should be templated with the derived class, e.g.
    * class Rot3 : public Testable<Rot3>. This allows us to define the
    * input type of equals as a Rot3 as well.
+	 * @ingroup base
    */
 	template <class Derived>
 	class Testable {

gtsam/base/blockMatrices.h

@@ -13,7 +13,7 @@
  * @file    blockMatrices.h
  * @brief   Access to matrices via blocks of pre-defined sizes.  Used in GaussianFactor and GaussianConditional.
  * @author  Richard Roberts
- * @created Sep 18, 2010
+ * @date    Sep 18, 2010
  */
 #pragma once
 
@@ -39,6 +39,8 @@ template<class MATRIX> class SymmetricBlockView;
  * determines the apparent *exclusive* last row for all operations.  To include
  * all rows, rowEnd() should be set to the number of rows in the matrix (i.e.
  * one after the last true row index).
+ *
+ * @ingroup base
  */
 template<class MATRIX>
 class VerticalBlockView {
@@ -313,6 +315,8 @@ private:
  * This class also has a parameter that can be changed after construction to
  * change the apparent matrix view.  firstBlock() determines the block that
  * appears to have index 0 for all operations (except re-setting firstBlock()).
+ *
+ * @ingroup base
  */
 template<class MATRIX>
 class SymmetricBlockView {

gtsam/base/cholesky.cpp

@@ -13,7 +13,7 @@
  * @file    cholesky.cpp
  * @brief   Efficient incomplete Cholesky on rank-deficient matrices, todo: constrained Cholesky
  * @author  Richard Roberts
- * @created Nov 5, 2010
+ * @date    Nov 5, 2010
  */
 
 #include <gtsam/base/debug.h>

gtsam/base/cholesky.h

@@ -13,7 +13,7 @@
  * @file    cholesky.h
  * @brief   Efficient incomplete Cholesky on rank-deficient matrices, todo: constrained Cholesky
  * @author  Richard Roberts
- * @created Nov 5, 2010
+ * @date    Nov 5, 2010
  */
 #pragma once
 

gtsam/base/debug.cpp

@@ -1,8 +1,8 @@
 /**
  * @file    debug.cpp
- * @brief   
+ * @brief   Global debugging flags
  * @author  Richard Roberts
- * @created Feb 1, 2011
+ * @date    Feb 1, 2011
  */
 
 #include <gtsam/base/debug.h>

gtsam/base/debug.h

@@ -2,7 +2,7 @@
  * @file    debug.h
  * @brief   Global debugging flags
  * @author  Richard Roberts
- * @created Feb 1, 2011
+ * @date    Feb 1, 2011
  */
 
 #include <gtsam/base/FastMap.h>

gtsam/base/timing.cpp

@@ -11,9 +11,9 @@
 
 /**
  * @file    timing.cpp
- * @brief   
+ * @brief   Timing utilities
  * @author  Richard Roberts, Michael Kaess
- * @created Oct 5, 2010
+ * @date 		Oct 5, 2010
  */
 
 #include <stdio.h>

gtsam/base/timing.h

@@ -11,9 +11,9 @@
 
 /**
  * @file    timing.h
- * @brief   
+ * @brief   Timing utilities
  * @author  Richard Roberts, Michael Kaess
- * @created Oct 5, 2010
+ * @date    Oct 5, 2010
  */
 #pragma once
 

gtsam/base/types.h

@@ -13,7 +13,8 @@
  * @file     types.h
  * @brief    Typedefs for easier changing of types
  * @author   Richard Roberts
- * @created Aug 21, 2010
+ * @date     Aug 21, 2010
+ * @defgroup base
  */
 
 #pragma once
@@ -22,12 +23,11 @@
 
 namespace gtsam {
 
-	/**
+	/// Integer variable index type
-	 * Integer variable index type
-	 */
 	typedef size_t Index;
 
-	/** Helper class that uses templates to select between two types based on
+	/**
+	 * Helper class that uses templates to select between two types based on
 	 * whether TEST_TYPE is const or not.
 	 */
 	template<typename TEST_TYPE, typename BASIC_TYPE, typename AS_NON_CONST,
@@ -40,6 +40,7 @@ namespace gtsam {
 	struct const_selector<BASIC_TYPE, BASIC_TYPE, AS_NON_CONST, AS_CONST> {
 		typedef AS_NON_CONST type;
 	};
+
 	/** Specialization for the const version */
 	template<typename BASIC_TYPE, typename AS_NON_CONST, typename AS_CONST>
 	struct const_selector<const BASIC_TYPE, BASIC_TYPE, AS_NON_CONST, AS_CONST> {