From 5cc106a24b5fe769fe00b3aa43e5208d1c2e50e7 Mon Sep 17 00:00:00 2001 From: Frank Dellaert Date: Wed, 7 Sep 2011 05:01:46 +0000 Subject: [PATCH] Documentation and creation of Doxygen module "base" --- gtsam/base/BTree.h | 17 ++++++++------- gtsam/base/DSF.h | 21 +++++++++++-------- gtsam/base/DSFVector.cpp | 12 +++++------ gtsam/base/DSFVector.h | 42 ++++++++++++++++++++------------------ gtsam/base/FastList.h | 3 ++- gtsam/base/FastMap.h | 4 ++-- gtsam/base/FastSet.h | 6 +++--- gtsam/base/FastVector.h | 8 ++++---- gtsam/base/Lie-inl.h | 10 ++++----- gtsam/base/Testable.h | 3 ++- gtsam/base/blockMatrices.h | 6 +++++- gtsam/base/cholesky.cpp | 2 +- gtsam/base/cholesky.h | 2 +- gtsam/base/debug.cpp | 4 ++-- gtsam/base/debug.h | 2 +- gtsam/base/timing.cpp | 4 ++-- gtsam/base/timing.h | 4 ++-- gtsam/base/types.h | 17 +++++++-------- 18 files changed, 91 insertions(+), 76 deletions(-) diff --git a/gtsam/base/BTree.h b/gtsam/base/BTree.h index 69db4d3a0..e0bb4c4a3 100644 --- a/gtsam/base/BTree.h +++ b/gtsam/base/BTree.h @@ -10,10 +10,11 @@ * -------------------------------------------------------------------------- */ /** - * Created on: Feb 3, 2010 - * @brief: purely functional binary tree - * @author Chris Beall - * @author Frank Dellaert + * @file BTree.h + * @brief purely functional binary tree + * @author Chris Beall + * @author Frank Dellaert + * @date Feb 3, 2010 */ #include @@ -24,7 +25,8 @@ namespace gtsam { /** - * @brief Binary tree + * @brief Binary tree + * @ingroup base */ template 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) { diff --git a/gtsam/base/DSF.h b/gtsam/base/DSF.h index 3f1f2df0e..ddc5b4836 100644 --- a/gtsam/base/DSF.h +++ b/gtsam/base/DSF.h @@ -10,14 +10,10 @@ * -------------------------------------------------------------------------- */ /** - * DSF.h - * - * Created on: Mar 26, 2010 - * @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. + * @file DSF.h + * @date Mar 26, 2010 + * @author Kai Ni + * @brief An implementation of Disjoint set forests (see CLR page 446 and up) */ #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 DSF : protected BTree { diff --git a/gtsam/base/DSFVector.cpp b/gtsam/base/DSFVector.cpp index 42a3bb96c..ceb33fc23 100644 --- a/gtsam/base/DSFVector.cpp +++ b/gtsam/base/DSFVector.cpp @@ -9,13 +9,11 @@ * -------------------------------------------------------------------------- */ -/* - * DSFVector.cpp - * - * Created on: Jun 25, 2010 - * Author: nikai - * Description: a faster implementation for DSF, which uses vector rather than btree. - * As a result, the size of the forest is prefixed. +/** + * @file DSFVector.cpp + * @date Jun 25, 2010 + * @author Kai Ni + * @brief a faster implementation for DSF, which uses vector rather than btree. */ #include diff --git a/gtsam/base/DSFVector.h b/gtsam/base/DSFVector.h index cb19b5461..17e897032 100644 --- a/gtsam/base/DSFVector.h +++ b/gtsam/base/DSFVector.h @@ -9,13 +9,11 @@ * -------------------------------------------------------------------------- */ -/* - * DSFVector.h - * - * Created on: Jun 25, 2010 - * @Author nikai - * @brief a faster implementation for DSF, which uses vector rather than btree. - * As a result, the size of the forest is prefixed. +/** + * @file DSFVector.h + * @date Jun 25, 2010 + * @author Kai Ni + * @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 V; - typedef size_t Label; - typedef std::vector::const_iterator const_iterator; - typedef std::vector::iterator iterator; + typedef std::vector V; ///< Vector of ints + typedef size_t Label; ///< Label type + typedef V::const_iterator const_iterator; ///< const iterator over V + typedef V::iterator iterator;///< iterator over V private: - boost::shared_ptr v_; // could use existing memory to improve the efficiency + // TODO could use existing memory to improve the efficiency + boost::shared_ptr v_; std::vector 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_in, const std::vector& 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 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 > sets() const; + + /// return all sets, i.e. a partition of all elements std::map > arrays() const; - // the in-place version of makeUnion + /// the in-place version of makeUnion void makeUnionInPlace(const size_t& i1, const size_t& i2); }; diff --git a/gtsam/base/FastList.h b/gtsam/base/FastList.h index ed993e3e8..bb0002545 100644 --- a/gtsam/base/FastList.h +++ b/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 class FastList: public std::list > { diff --git a/gtsam/base/FastMap.h b/gtsam/base/FastMap.h index ea2468d64..d4535ba1e 100644 --- a/gtsam/base/FastMap.h +++ b/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 class FastMap : public std::map, boost::fast_pool_allocator > > { diff --git a/gtsam/base/FastSet.h b/gtsam/base/FastSet.h index 391521ecc..038921f91 100644 --- a/gtsam/base/FastSet.h +++ b/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 - * percent. + * we've seen that the fast_pool_allocator can lead to speedups of several %. + * @ingroup base */ template class FastSet : public std::set, boost::fast_pool_allocator > { diff --git a/gtsam/base/FastVector.h b/gtsam/base/FastVector.h index 2e87d638a..44772e3e2 100644 --- a/gtsam/base/FastVector.h +++ b/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 - * percent. + * we've seen that the pool_allocator can lead to speedups of several % + * @ingroup base */ template class FastVector: public std::vector > { diff --git a/gtsam/base/Lie-inl.h b/gtsam/base/Lie-inl.h index fc7a4fdea..559a01960 100644 --- a/gtsam/base/Lie-inl.h +++ b/gtsam/base/Lie-inl.h @@ -9,11 +9,11 @@ * -------------------------------------------------------------------------- */ -/* - * LieBaseImplementations.h - * - * Created on: Jan 9, 2010 - * Author: richard +/** + * @file Lie-inl.h + * @date Jan 9, 2010 + * @author Richard Roberts + * @brief Instantiate macro for Lie type */ #pragma once diff --git a/gtsam/base/Testable.h b/gtsam/base/Testable.h index 8e62e08e1..b09591ae6 100644 --- a/gtsam/base/Testable.h +++ b/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. This allows us to define the * input type of equals as a Rot3 as well. + * @ingroup base */ template class Testable { diff --git a/gtsam/base/blockMatrices.h b/gtsam/base/blockMatrices.h index f24290c15..f1dd02357 100644 --- a/gtsam/base/blockMatrices.h +++ b/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 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 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 SymmetricBlockView { diff --git a/gtsam/base/cholesky.cpp b/gtsam/base/cholesky.cpp index 670f0b9c2..0b03e7bda 100644 --- a/gtsam/base/cholesky.cpp +++ b/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 diff --git a/gtsam/base/cholesky.h b/gtsam/base/cholesky.h index a71d72da1..46463dbc9 100644 --- a/gtsam/base/cholesky.h +++ b/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 diff --git a/gtsam/base/debug.cpp b/gtsam/base/debug.cpp index 4da6dc6c6..144d63e08 100644 --- a/gtsam/base/debug.cpp +++ b/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 diff --git a/gtsam/base/debug.h b/gtsam/base/debug.h index 51074bd46..970470ed0 100644 --- a/gtsam/base/debug.h +++ b/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 diff --git a/gtsam/base/timing.cpp b/gtsam/base/timing.cpp index fba804885..0942735ad 100644 --- a/gtsam/base/timing.cpp +++ b/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 diff --git a/gtsam/base/timing.h b/gtsam/base/timing.h index f1622e500..e91cbb232 100644 --- a/gtsam/base/timing.h +++ b/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 diff --git a/gtsam/base/types.h b/gtsam/base/types.h index 575d53806..b6c5617a5 100644 --- a/gtsam/base/types.h +++ b/gtsam/base/types.h @@ -10,10 +10,11 @@ * -------------------------------------------------------------------------- */ /** - * @file types.h - * @brief Typedefs for easier changing of types - * @author Richard Roberts - * @created Aug 21, 2010 + * @file types.h + * @brief Typedefs for easier changing of types + * @author Richard Roberts + * @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 { typedef AS_NON_CONST type; }; + /** Specialization for the const version */ template struct const_selector {