Fix #11 - Distance computation shall be better documented.

4 files changed, 47 insertions, 22 deletions

diff --git a/src/Bottleneck_distance/doc/Intro_bottleneck_distance.h b/src/Bottleneck_distance/doc/Intro_bottleneck_distance.h
index 6fd058a8..49137ee1 100644
--- a/src/Bottleneck_distance/doc/Intro_bottleneck_distance.h
+++ b/src/Bottleneck_distance/doc/Intro_bottleneck_distance.h
@@ -6,6 +6,9 @@
  *
  *    Copyright (C) 2015 Inria
  *
+ *    Modifications:
+ *      - 2019/06 Vincent Rouvreau : Fix #11 - Distance computation shall be better documented.
+ *
  *    This program is free software: you can redistribute it and/or modify
  *    it under the terms of the GNU General Public License as published by
  *    the Free Software Foundation, either version 3 of the License, or
@@ -44,6 +47,43 @@ namespace persistence_diagram {
  * This implementation is based on ideas from "Geometry Helps in Bottleneck Matching and Related Problems"
  * \cite DBLP:journals/algorithmica/EfratIK01. Another relevant publication, although it was not used is
  * "Geometry Helps to Compare Persistence Diagrams" \cite Kerber:2017:GHC:3047249.3064175.
+ * 
+ * \section bottleneckdistanceprecision Distance computation
+ *
+ * Bottleneck distance does not use Euclidean distance, like explained in the following example:
+ *
+ * \code{.cpp}
+#include <gudhi/Bottleneck.h>
+
+#include <iostream>
+#include <vector>
+#include <utility>  // for pair
+
+int main() {
+  std::vector< std::pair<double, double> > diag1, diag2;
+  diag1.emplace_back(0., 0.);
+  diag2.emplace_back(0., 13.);
+
+  double b = Gudhi::persistence_diagram::bottleneck_distance(diag1, diag2);
+  std::cout << "Bottleneck distance = " << b << std::endl;
+}
+ * \endcode
+ *
+ * \code Bottleneck distance = 6.5
+ * \endcode
+ *
+ * \image html bottleneck_distance_example.png The point (0, 13) is at 6.5 distance from the diagonal and more specifically from the point (6.5, 6.5)
+ *
+ * \section bottleneckbasicexample Basic example
+ *
+ * This another example computes the bottleneck distance from 2 persistence diagrams:
+ * \include Bottleneck_distance/bottleneck_basic_example.cpp
+ *
+ * \code
+    Bottleneck distance = 0.75
+    Approx bottleneck distance = 0.808176
+ * \endcode
+
  */
 /** @} */  // end defgroup bottleneck_distance
 
diff --git a/src/Bottleneck_distance/doc/bottleneck_distance_example.png b/src/Bottleneck_distance/doc/bottleneck_distance_example.png
index fb6847c8..b56ee791 100644
--- a/src/Bottleneck_distance/doc/bottleneck_distance_example.png
+++ b/src/Bottleneck_distance/doc/bottleneck_distance_example.png
diff --git a/src/Bottleneck_distance/example/bottleneck_basic_example.cpp b/src/Bottleneck_distance/example/bottleneck_basic_example.cpp
index 3df7d12d..61778a55 100644
--- a/src/Bottleneck_distance/example/bottleneck_basic_example.cpp
+++ b/src/Bottleneck_distance/example/bottleneck_basic_example.cpp
@@ -1,25 +1,3 @@
-/*    This file is part of the Gudhi Library. The Gudhi library
- *    (Geometric Understanding in Higher Dimensions) is a generic C++
- *    library for computational topology.
- *
- *    Authors:       Francois Godi, small modifications by Pawel Dlotko
- *
- *    Copyright (C) 2015 Inria
- *
- *    This program is free software: you can redistribute it and/or modify
- *    it under the terms of the GNU General Public License as published by
- *    the Free Software Foundation, either version 3 of the License, or
- *    (at your option) any later version.
- *
- *    This program is distributed in the hope that it will be useful,
- *    but WITHOUT ANY WARRANTY; without even the implied warranty of
- *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- *    GNU General Public License for more details.
- *
- *    You should have received a copy of the GNU General Public License
- *    along with this program.  If not, see <http://www.gnu.org/licenses/>.
- */
-
 #include <gudhi/Bottleneck.h>
 
 #include <iostream>
diff --git a/src/Bottleneck_distance/include/gudhi/Bottleneck.h b/src/Bottleneck_distance/include/gudhi/Bottleneck.h
index 7a553006..4ce6cacc 100644
--- a/src/Bottleneck_distance/include/gudhi/Bottleneck.h
+++ b/src/Bottleneck_distance/include/gudhi/Bottleneck.h
@@ -6,6 +6,9 @@
  *
  *    Copyright (C) 2015 Inria
  *
+ *    Modifications:
+ *      - 2019/06 Vincent Rouvreau : Fix doxygen warning.
+ *
  *    This program is free software: you can redistribute it and/or modify
  *    it under the terms of the GNU General Public License as published by
  *    the Free Software Foundation, either version 3 of the License, or
@@ -92,6 +95,10 @@ inline double bottleneck_distance_exact(Persistence_graph& g) {
  *
  * \tparam Persistence_diagram1,Persistence_diagram2
  * models of the concept `PersistenceDiagram`.
+ *
+ * \param[in] diag1 The first persistence diagram.
+ * \param[in] diag2 The second persistence diagram.
+ *
  * \param[in] e
  * \parblock
  * If `e` is 0, this uses an expensive algorithm to compute the exact distance.