Merge bottleneck-doc-glisse dev in trunk

git-svn-id: svn+ssh://scm.gforge.inria.fr/svnroot/gudhi/trunk@2012 636b058d-ea47-450e-bf9e-a15bfbe3eedb

Former-commit-id: 52eadba00ed5f4e072dbee58de00b0f68b1f0cfb

4 files changed, 27 insertions, 15 deletions

diff --git a/src/Bottleneck_distance/concept/Persistence_diagram.h b/src/Bottleneck_distance/concept/Persistence_diagram.h
index 2706716b..b157f22a 100644
--- a/src/Bottleneck_distance/concept/Persistence_diagram.h
+++ b/src/Bottleneck_distance/concept/Persistence_diagram.h
@@ -25,24 +25,25 @@
 
 namespace Gudhi {
 
-namespace bottleneck_distance {
+namespace persistence_diagram {
 
-/** \brief Concept of Diagram_point. std::get<0>(point) must return the birth of the corresponding component and std::get<1>(point) its death.
+/** \brief Concept of point in a persistence diagram. std::get<0>(point) must return the birth of the corresponding component and std::get<1>(point) its death.
+ * Both should be convertible to `double`.
  * A valid implementation of this concept is std::pair<double,double>.
  * Death should be larger than birth, death can be std::numeric_limits<double>::infinity() for components which stay alive.
  *
  * \ingroup bottleneck_distance
  */
-typename Diagram_point;
+struct DiagramPoint{};
 
-/** \brief Concept of persistence diagram. It's a range of Diagram_point.
+/** \brief Concept of persistence diagram. It is a range of `DiagramPoint`.
  * std::begin(diagram) and std::end(diagram) must return corresponding iterators.
  *
  * \ingroup bottleneck_distance
  */
-typename Persistence_Diagram;
+struct PersistenceDiagram{};
 
-}  // namespace bottleneck_distance
+}  // namespace persistence_diagram
 
 }  // namespace Gudhi
 
diff --git a/src/Bottleneck_distance/doc/Intro_bottleneck_distance.h b/src/Bottleneck_distance/doc/Intro_bottleneck_distance.h
index 21187f9c..5223678d 100644
--- a/src/Bottleneck_distance/doc/Intro_bottleneck_distance.h
+++ b/src/Bottleneck_distance/doc/Intro_bottleneck_distance.h
@@ -26,7 +26,7 @@
 // needs namespace for Doxygen to link on classes
 namespace Gudhi {
 // needs namespace for Doxygen to link on classes
-namespace bottleneck_distance {
+namespace persistence_diagram {
 
 /**  \defgroup bottleneck_distance Bottleneck distance
  * 
@@ -35,7 +35,7 @@ namespace bottleneck_distance {
  * 
  * \section bottleneckdefinition Definition
  * 
- * The bottleneck distance measures the similarity between two persistence diagrams. It's the shortest distance b for which there exists a perfect matching between
+ * The bottleneck distance measures the similarity between two persistence diagrams. It is the shortest distance b for which there exists a perfect matching between
  * the points of the two diagrams (completed with all the points on the diagonal in order to ignore cardinality mismatchs) such that
  * any couple of matched points are at distance at most b.
  *
@@ -44,7 +44,7 @@ namespace bottleneck_distance {
  */
 /** @} */  // end defgroup bottleneck_distance
 
-}  // namespace bottleneck_distance
+}  // namespace persistence_diagram
 
 }  // namespace Gudhi
 
diff --git a/src/Bottleneck_distance/include/gudhi/Bottleneck.h b/src/Bottleneck_distance/include/gudhi/Bottleneck.h
index b5641e29..b90a0ee0 100644
--- a/src/Bottleneck_distance/include/gudhi/Bottleneck.h
+++ b/src/Bottleneck_distance/include/gudhi/Bottleneck.h
@@ -80,11 +80,22 @@ double bottleneck_distance_exact(Persistence_graph& g) {
   return sd.at(lower_bound_i);
 }
 
-/** \brief Function to use in order to compute the Bottleneck distance between two persistence diagrams (see concepts).
- * If the last parameter e is not 0, you get an additive e-approximation, which is a lot faster to compute whatever is
- * e.
- * Thus, by default, e is a very small positive double, actually the smallest double possible such that the
- * floating-point inaccuracies don't lead to a failure of the algorithm.
+/** \brief Function to compute the Bottleneck distance between two persistence diagrams.
+ *
+ * \tparam Persistence_diagram1,Persistence_diagram2
+ * models of the concept `PersistenceDiagram`.
+ * \param[in] e
+ * \parblock
+ * If `e` is 0, this uses an expensive algorithm to compute the exact distance.
+ *
+ * If `e` is not 0, it asks for an additive `e`-approximation, and currently
+ * also allows a small multiplicative error (the last 2 or 3 bits of the
+ * mantissa may be wrong). This version of the algorithm takes advantage of the
+ * limited precision of `double` and is usually a lot faster to compute,
+ * whatever the value of `e`.
+ *
+ * Thus, by default, `e` is the smallest positive double.
+ * \endparblock
  *
  * \ingroup bottleneck_distance
  */
diff --git a/src/Bottleneck_distance/include/gudhi/Persistence_graph.h b/src/Bottleneck_distance/include/gudhi/Persistence_graph.h
index 39efc082..c7695112 100644
--- a/src/Bottleneck_distance/include/gudhi/Persistence_graph.h
+++ b/src/Bottleneck_distance/include/gudhi/Persistence_graph.h
@@ -40,7 +40,7 @@ namespace persistence_diagram {
  */
 class Persistence_graph {
  public:
-  /** \internal \brief Constructor taking 2 Persistence_Diagrams (concept) as parameters. */
+  /** \internal \brief Constructor taking 2 PersistenceDiagrams (concept) as parameters. */
   template<typename Persistence_diagram1, typename Persistence_diagram2>
   Persistence_graph(const Persistence_diagram1& diag1, const Persistence_diagram2& diag2, double e);
   /** \internal \brief Is the given point from U the projection of a point in V ? */