Added a big chunk of documentation. +small fixes

git-svn-id: svn+ssh://scm.gforge.inria.fr/svnroot/gudhi/branches/relaxed-witness@1679 636b058d-ea47-450e-bf9e-a15bfbe3eedb

Former-commit-id: d3166034bf662121bc21583bb027c67f736e904c

4 files changed, 74 insertions, 31 deletions

diff --git a/src/Witness_complex/include/gudhi/Active_witness/Active_witness.h b/src/Witness_complex/include/gudhi/Active_witness/Active_witness.h
index e52410e4..2ca76767 100644
--- a/src/Witness_complex/include/gudhi/Active_witness/Active_witness.h
+++ b/src/Witness_complex/include/gudhi/Active_witness/Active_witness.h
@@ -31,9 +31,10 @@ namespace Gudhi {
 
 namespace witness_complex {
 
-  /** \brief Class representing a list of nearest neighbors to a given witness.
-   *  \detail Every element is a pair of a landmark identifier and the squared distance to it.
-   */
+  //  /** \class Active_witness
+  // *  \brief Class representing a list of nearest neighbors to a given witness.
+  // *  \details Every element is a pair of a landmark identifier and the squared distance to it.
+  // */
 template< typename Id_distance_pair,
           typename INS_range >
 class Active_witness {
diff --git a/src/Witness_complex/include/gudhi/Active_witness/Active_witness_iterator.h b/src/Witness_complex/include/gudhi/Active_witness/Active_witness_iterator.h
index 9c96f7e8..38c7adb2 100644
--- a/src/Witness_complex/include/gudhi/Active_witness/Active_witness_iterator.h
+++ b/src/Witness_complex/include/gudhi/Active_witness/Active_witness_iterator.h
@@ -31,12 +31,12 @@ namespace Gudhi {
 
 namespace witness_complex {
 
-  /** \brief Iterator in the nearest landmark list.
-   *  \detail After the iterator reaches the end of the list,
-   *          the list is augmented by a (nearest landmark, distance) pair if possible.
-   *          If all the landmarks are present in the list, iterator returns the specific end value
-   *          of the corresponding 'Active_witness' object.
-   */
+  //  /** \brief Iterator in the nearest landmark list.
+  //   *  \details After the iterator reaches the end of the list,
+  //   *          the list is augmented by a (nearest landmark, distance) pair if possible.
+  //   *          If all the landmarks are present in the list, iterator returns the specific end value
+  //   *          of the corresponding 'Active_witness' object.
+  //   */
   
 template< typename Active_witness,
           typename Id_distance_pair,
diff --git a/src/Witness_complex/include/gudhi/Strong_witness_complex.h b/src/Witness_complex/include/gudhi/Strong_witness_complex.h
index 1ce050ad..e64f8f20 100644
--- a/src/Witness_complex/include/gudhi/Strong_witness_complex.h
+++ b/src/Witness_complex/include/gudhi/Strong_witness_complex.h
@@ -37,6 +37,22 @@ namespace Gudhi {
   
 namespace witness_complex {
 
+/**
+ *  \private
+ * \class Strong_witness_complex
+ * \brief Constructs strong witness complex for the given sets of witnesses and landmarks.
+ * \ingroup witness_complex
+ *
+ * \tparam Kernel_ requires a <a target="_blank"
+ * href="http://doc.cgal.org/latest/Kernel_d/classCGAL_1_1Epick__d.html">CGAL::Epick_d</a> class, which
+ * can be static if you know the ambiant dimension at compile-time, or dynamic if you don't.
+ * \tparam DimensionTag can be either <a target="_blank"
+ * href="http://doc.cgal.org/latest/Kernel_23/classCGAL_1_1Dimension__tag.html">Dimension_tag<d></a>
+ * if you know the intrinsic dimension at compile-time,
+ * or <a target="_blank"
+ * href="http://doc.cgal.org/latest/Kernel_23/classCGAL_1_1Dynamic__dimension__tag.html">CGAL::Dynamic_dimension_tag</a>
+ * if you don't.
+ */
 template< class Kernel_ >
 class Strong_witness_complex {
 private:
@@ -55,7 +71,7 @@ private:
   typedef FT Filtration_value;
 
   
-  typedef std::ptrdiff_t Witness_id;
+  typedef std::size_t Witness_id;
   typedef typename Nearest_landmark_range::Point_with_transformed_distance Id_distance_pair;
   typedef typename Id_distance_pair::first_type Landmark_id;
   typedef Active_witness<Id_distance_pair, Nearest_landmark_range> ActiveWitness;
@@ -63,6 +79,8 @@ private:
   typedef std::vector< Landmark_id > typeVectorVertex;
   typedef std::pair< typeVectorVertex, Filtration_value> typeSimplex;
 
+  typedef Landmark_id Vertex_handle;
+  
  private:
   Point_range                         witnesses_, landmarks_;
   Kd_tree                             landmark_tree_;
@@ -74,9 +92,13 @@ private:
 
   //@{
 
-  /*
+  /**
    *  \brief Initializes member variables before constructing simplicial complex.
-   *  \details The parameters should satisfy InputIterator C++ concepts.
+   *  \details Records landmarks from the range [landmarks_first, landmarks_last) into a 
+   *           table internally, as well as witnesses from the range [witnesses_first, witnesses_last).
+   *           All iterator parameters should satisfy <a target="_blank"
+   *           href="http://en.cppreference.com/w/cpp/concept/InputIterator">InputIterator</a>
+   *           C++ concept.
    */
   template< typename InputIteratorLandmarks,
             typename InputIteratorWitnesses >
@@ -90,15 +112,17 @@ private:
 
   /** \brief Returns the point corresponding to the given vertex.
    */
-  Point_d get_point( std::size_t vertex ) const
+  template <typename Vertex_handle> 
+  Point_d get_point( Vertex_handle vertex ) const
   {
     return landmarks_[vertex];
   }
   
-  /** \brief Outputs the (strong) witness complex with 
-   *         squared relaxation parameter 'max_alpha_square'
-   *         to simplicial complex 'complex'.
-   *         The parameter 'limit_dimension' represents the maximal dimension of the simplicial complex
+  /** \brief Outputs the strong witness complex in a simplicial complex data structure.
+   *  @param[out] complex Simplicial complex data structure compatible with 'find' and 'insert' operations.
+   *              (Cf SimplicialComplexForWitness)
+   *  @param[in] max_alpha_square Maximal squared relaxation parameter.
+   *  @param[in] limit_dimension Represents the maximal dimension of the simplicial complex
    *         (default value = no limit).
    */
   template < typename SimplicialComplexForWitness >
diff --git a/src/Witness_complex/include/gudhi/Witness_complex.h b/src/Witness_complex/include/gudhi/Witness_complex.h
index 7b46e1c0..6a944c43 100644
--- a/src/Witness_complex/include/gudhi/Witness_complex.h
+++ b/src/Witness_complex/include/gudhi/Witness_complex.h
@@ -37,12 +37,22 @@ namespace Gudhi {
   
 namespace witness_complex {
 
-// /*
-//  *  \private
-//     \class Witness_complex
-//     \brief Constructs the witness complex for the given set of witnesses and landmarks.
-//     \ingroup witness_complex
-//  */
+/**
+ * \private
+ * \class Witness_complex
+ * \brief Constructs (weak) witness complex for the given sets of witnesses and landmarks.
+ * \ingroup witness_complex
+ *
+ * \tparam Kernel_ requires a <a target="_blank"
+ * href="http://doc.cgal.org/latest/Kernel_d/classCGAL_1_1Epick__d.html">CGAL::Epick_d</a> class, which
+ * can be static if you know the ambiant dimension at compile-time, or dynamic if you don't.
+ * \tparam DimensionTag can be either <a target="_blank"
+ * href="http://doc.cgal.org/latest/Kernel_23/classCGAL_1_1Dimension__tag.html">Dimension_tag<d></a>
+ * if you know the intrinsic dimension at compile-time,
+ * or <a target="_blank"
+ * href="http://doc.cgal.org/latest/Kernel_23/classCGAL_1_1Dynamic__dimension__tag.html">CGAL::Dynamic_dimension_tag</a>
+ * if you don't.
+*/
 template< class Kernel_ >
 class Witness_complex {
 private:
@@ -69,6 +79,8 @@ private:
   typedef std::vector< Landmark_id > typeVectorVertex;
   typedef std::pair< typeVectorVertex, Filtration_value> typeSimplex;
 
+  typedef Landmark_id Vertex_handle;
+
  private:
   Point_range                         witnesses_, landmarks_;
   Kd_tree                             landmark_tree_;
@@ -80,9 +92,13 @@ private:
 
   //@{
 
-  /*
+  /**
    *  \brief Initializes member variables before constructing simplicial complex.
-   *  \details The parameters should satisfy InputIterator C++ concepts.
+   *  \details Records landmarks from the range [landmarks_first, landmarks_last) into a 
+   *           table internally, as well as witnesses from the range [witnesses_first, witnesses_last).
+   *           All iterator parameters should satisfy <a target="_blank"
+   *           href="http://en.cppreference.com/w/cpp/concept/InputIterator">InputIterator</a>
+   *           C++ concept.
    */
   template< typename InputIteratorLandmarks,
             typename InputIteratorWitnesses >
@@ -95,16 +111,18 @@ private:
   }
 
   /** \brief Returns the point corresponding to the given vertex.
+   *  @param[in] vertex Vertex handle of the point to retrieve.
    */
-  Point_d get_point( std::size_t vertex ) const
+  Point_d get_point( Vertex_handle vertex ) const
   {
     return landmarks_[vertex];
   }
   
-  /** \brief Outputs the (weak) witness complex with 
-   *         squared relaxation parameter 'max_alpha_square'
-   *         to simplicial complex 'complex'.
-   *         The parameter 'limit_dimension' represents the maximal dimension of the simplicial complex
+  /** \brief Outputs the (weak) witness complex in a simplicial complex data structure.
+   *  @param[out] complex Simplicial complex data structure compatible with 'find' and 'insert' operations.
+   *              (Cf SimplicialComplexForWitness)
+   *  @param[in] max_alpha_square Maximal squared relaxation parameter.
+   *  @param[in] limit_dimension Represents the maximal dimension of the simplicial complex
    *         (default value = no limit).
    */
   template < typename SimplicialComplexForWitness >
@@ -229,7 +247,7 @@ private:
     return will_be_active;
   }
   
-  /** \brief Check if the facets of the k-dimensional simplex witnessed 
+  /* \brief Check if the facets of the k-dimensional simplex witnessed 
    *  by witness witness_id are already in the complex.
    *  inserted_vertex is the handle of the (k+1)-th vertex witnessed by witness_id
    */