[mlpack-git] master: Add documentation to NSModel visitors. (5e01635)

[gitdub at mlpack.org]

Repository : https://github.com/mlpack/mlpack
On branch  : master
Link       : https://github.com/mlpack/mlpack/compare/809ed4bf33cef9de8412fc167cb0e356a369e3b6...eaa7182ebed8cce3fd6191dc1f8170546ea297da

>---------------------------------------------------------------

commit 5e01635efabfc5dad85478ec8bed61f5295a9799
Author: Ryan Curtin <ryan at ratml.org>
Date:   Wed Jun 29 11:51:13 2016 -0400

    Add documentation to NSModel visitors.


>---------------------------------------------------------------

5e01635efabfc5dad85478ec8bed61f5295a9799
 src/mlpack/methods/neighbor_search/ns_model.hpp | 29 +++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/src/mlpack/methods/neighbor_search/ns_model.hpp b/src/mlpack/methods/neighbor_search/ns_model.hpp
index 55e9e91..5001675 100644
--- a/src/mlpack/methods/neighbor_search/ns_model.hpp
+++ b/src/mlpack/methods/neighbor_search/ns_model.hpp
@@ -59,14 +59,19 @@ struct NSModelName<FurthestNeighborSort>
 class MonoSearchVisitor : public boost::static_visitor<void>
 {
  private:
+  //! Number of neighbors to search for.
   const size_t k;
+  //! Result matrix for neighbors.
   arma::Mat<size_t>& neighbors;
+  //! Result matrix for distances.
   arma::mat& distances;
 
  public:
+  //! Perform monochromatic nearest neighbor search.
   template<typename NSType>
   void operator()(NSType* ns) const;
 
+  //! Construct the MonoSearchVisitor object with the given parameters.
   MonoSearchVisitor(const size_t k,
                     arma::Mat<size_t>& neighbors,
                     arma::mat& distances) :
@@ -86,10 +91,15 @@ template<typename SortPolicy>
 class BiSearchVisitor : public boost::static_visitor<void>
 {
  private:
+  //! The query set for the bichromatic search.
   const arma::mat& querySet;
+  //! The number of neighbors to search for.
   const size_t k;
+  //! The result matrix for neighbors.
   arma::Mat<size_t>& neighbors;
+  //! The result matrix for distances.
   arma::mat& distances;
+  //! The number of points in a leaf (for BinarySpaceTrees).
   const size_t leafSize;
 
   //! Bichromatic neighbor search on the given NSType considering the leafSize.
@@ -115,6 +125,7 @@ class BiSearchVisitor : public boost::static_visitor<void>
   //! Bichromatic neighbor search on the given NSType specialized for BallTrees.
   void operator()(NSTypeT<tree::BallTree>* ns) const;
 
+  //! Construct the BiSearchVisitor.
   BiSearchVisitor(const arma::mat& querySet,
                   const size_t k,
                   arma::Mat<size_t>& neighbors,
@@ -132,7 +143,9 @@ template<typename SortPolicy>
 class TrainVisitor : public boost::static_visitor<void>
 {
  private:
+  //! The reference set to use for training.
   arma::mat&& referenceSet;
+  //! The leaf size, used only by BinarySpaceTree.
   size_t leafSize;
 
   //! Train on the given NSType considering the leafSize.
@@ -158,6 +171,8 @@ class TrainVisitor : public boost::static_visitor<void>
   //! Train on the given NSType specialized for BallTrees.
   void operator()(NSTypeT<tree::BallTree>* ns) const;
 
+  //! Construct the TrainVisitor object with the given reference set and leaf
+  //! size for BinarySpaceTrees.
   TrainVisitor(arma::mat&& referenceSet, const size_t leafSize);
 };
 
@@ -167,6 +182,7 @@ class TrainVisitor : public boost::static_visitor<void>
 class SingleModeVisitor : public boost::static_visitor<bool&>
 {
  public:
+  //! Return whether or not single-tree search is enabled.
   template<typename NSType>
   bool& operator()(NSType* ns) const;
 };
@@ -177,6 +193,7 @@ class SingleModeVisitor : public boost::static_visitor<bool&>
 class NaiveVisitor : public boost::static_visitor<bool&>
 {
  public:
+  //! Return whether or not naive search is enabled.
   template<typename NSType>
   bool& operator()(NSType *ns) const;
 };
@@ -187,6 +204,7 @@ class NaiveVisitor : public boost::static_visitor<bool&>
 class EpsilonVisitor : public boost::static_visitor<double&>
 {
  public:
+  //! Return epsilon, the approximation parameter.
   template<typename NSType>
   double& operator()(NSType *ns) const;
 };
@@ -197,6 +215,7 @@ class EpsilonVisitor : public boost::static_visitor<double&>
 class ReferenceSetVisitor : public boost::static_visitor<const arma::mat&>
 {
  public:
+  //! Return the reference set.
   template<typename NSType>
   const arma::mat& operator()(NSType *ns) const;
 };
@@ -207,13 +226,18 @@ class ReferenceSetVisitor : public boost::static_visitor<const arma::mat&>
 class DeleteVisitor : public boost::static_visitor<void>
 {
  public:
+  //! Delete the NSType object.
   template<typename NSType>
   void operator()(NSType *ns) const;
 };
 
 /**
  * The NSModel class provides an easy way to serialize a model, abstracts away
- * the different types of trees, and also reflects the NeighborSearch API.
+ * the different types of trees, and also reflects the NeighborSearch API.  This
+ * class is meant to be used by the command-line mlpack_knn and mlpack_kfn
+ * programs, and thus does not have the same complete functionality and
+ * flexibility as the NeighborSearch class.  So if you are using it outside of
+ * mlpack_knn and mlpack_kfn, be aware that it is limited!
  *
  * @tparam SortPolicy The sort policy for distances; see NearestNeighborSort.
  */
@@ -240,8 +264,9 @@ class NSModel
   //! For tree types that accept the maxLeafSize parameter.
   size_t leafSize;
 
-  //! For random projections.
+  //! If true, random projections are used.
   bool randomBasis;
+  //! This is the random projection matrix; only used if randomBasis is true.
   arma::mat q;
 
   /**