Improve documentation

Documentation/doxyassist.xml

@@ -111,6 +111,7 @@ namespace for the XML file to be processed properly.  -->
 
           <list name="TAGFILES" append="true">
             <item>./tags/Triangulation_2.tag=../../CGAL.CGAL.2D-Triangulation/html</item>
+            <item>./tags/Polygon.tag=../../CGAL.CGAL.2D-Polygons/html</item>
           </list>
         </doxygen>
       </project>

Polyline_simplification_2/doc/Polyline_simplification_2/Concepts/PolylineSimplificationStopPredicate.h

@@ -1,22 +1,29 @@
-/// Models of this concept are passed to the polyline simplification algorithm to indicate
+/*!
-/// when to stop the process.
+\ingroup PkgPolylineSimplification2Concepts
-///
+\cgalConcept
-/// @heading Has Models:
+
-/// - CGAL::Polyline_simplification_2::Stop_below_count_ratio_threshold
+Models of this concept are passed to the polyline simplification algorithm to indicate
-/// - CGAL::Polyline_simplification_2::Stop_below_count_threshold
+when to stop the process.
-/// - CGAL::Polyline_simplification_2::Stop_above_cost_threshold
+
+\cgalHasModel `CGAL::Polyline_simplification_2::Stop_below_count_ratio_threshold`
+\cgalHasModel `CGAL::Polyline_simplification_2::Stop_below_count_threshold`
+\cgalHasModel `CGAL::Polyline_simplification_2::Stop_above_cost_threshold`
+*/
+
 class PolylineSimplificationStopPredicate
 {
 public :
-
+  /*!
-  /// Indicates if the simplification must be stoped.
+  Indicates if the simplification must be stopped.
-  /// This is called right before each vertex is about to be removed
+  This is called right before each vertex is about to be removed
-  /// @param cdt The underlying constrained Delaunay triangulation which embeeds the polyline set
+  \param cdt The underlying constrained Delaunay triangulation which 
-  /// @param q The current vertex about to be removed (given as a PolylineSimplificationVertex)
+  embeds the polyline set
-  /// @param cost The associated cost for removing the current vertex (as given by 'PolylineSimplificationCostFunction')
+  \param q The current vertex about to be removed (given as a `PolylineSimplificationVertex`)
-  /// @param initial_count The initial number of vertices in the entire polyline set (including intersection vertices not in any source polyline)
+  \param cost The associated cost for removing the current vertex (as given by `PolylineSimplificationCostFunction`)
-  /// @param current_count The current number of vertices
+  \param initial_count The initial number of vertices in the entire polyline set (including intersection vertices not in any source polyline)
-  /// @return true if the algorithm should stop, false if it should continue
+  \param current_count The current number of vertices
+  \return `true` if the algorithm should stop, `false` if it should continue
+  */
   template<class ConstrainedDelaunayTriangulation, class VertexHandle>
   bool operator()( ConstrainedDelaunayTriangulation const& cdt
                  , VertexHandle const& q

Polyline_simplification_2/doc/Polyline_simplification_2/PackageDescription.txt

@@ -2,10 +2,13 @@
 /// \defgroup PkgPolylineSimplification2Concepts Concepts
 /// \ingroup PkgPolylineSimplification2
 
-/// \defgroup PkgPolylineSimplification2PolylineSimplificationClasses PolylineSimplification Classes
+/// \defgroup PkgPolylineSimplification2Classes Polyline Simplification Classes
 /// \ingroup PkgPolylineSimplification2
 
 
+/// \defgroup PkgPolylineSimplification2Functions Global Functions
+/// \ingroup PkgPolylineSimplification2
+
 
 
 /*!
@@ -34,14 +37,10 @@
 - `PolylineSimplificationCostFunction`
 - `PolylineSimplificationStopPredicate`
 
-## Classes ##
-
-- `CGAL::Polyline_simplification_2<Traits>`
-
 
 ## Global Functions ##
-- `CGAL::Polyline_simplification::simplify()`
+- `CGAL::Polyline_simplification_2::simplify()`
-- `CGAL::Polyline_simplification::mark_vertices_unremovable()`
+- `CGAL::Polyline_simplification_2::mark_vertices_unremovable()`
 
 */
 

Polyline_simplification_2/include/CGAL/Polyline_simplification_2/Hybrid_squared_distance_cost.h

@@ -25,11 +25,13 @@ namespace CGAL {
 
 namespace Polyline_simplification_2
 {
+/// \addtogroup PkgPolylineSimplification2Classes
+/// @{
 
 /// This class is a cost function which calculates the cost as the square of the distance between the original and simplified polylines,
 /// possibly scaled based on a factor.
 ///
-/// @heading Is Model for the Concepts: `PolylineSimplificationCostFunction`.
+/// \cgalModels `PolylineSimplificationCostFunction`.
 template<class FT>
 class Hybrid_squared_distance_cost
 {
@@ -93,6 +95,7 @@ private:
 
 };
 
+/// @}
 
 } // namespace Polyline_simplification_2
 

Polyline_simplification_2/include/CGAL/Polyline_simplification_2/Scaled_squared_distance_cost.h

@@ -25,6 +25,8 @@ namespace CGAL {
 
 namespace Polyline_simplification_2
 {
+/// \addtogroup PkgPolylineSimplification2Classes
+/// @{
 
 /// This class is a cost function which calculates the cost as a scaled variant of the square of the distance between the original and simplified polylines.
 ///
@@ -34,7 +36,7 @@ class Scaled_squared_distance_cost
 
 public:
 
-  /// Initializes the cost function
+  /// Initializes the cost function.
   Scaled_squared_distance_cost() {}
 
   /// Returns the maximal square distances between each point along the original subpolyline,
@@ -86,6 +88,7 @@ public:
 
 };
 
+/// @}
 
 } // namespace Polyline_simplification_2
 

Polyline_simplification_2/include/CGAL/Polyline_simplification_2/Squared_distance_cost.h

@@ -26,6 +26,8 @@ namespace CGAL {
 namespace Polyline_simplification_2
 {
 
+/// \addtogroup PkgPolylineSimplification2Classes
+/// @{
 /// This class is a cost function which calculates the cost as the square of the distance between the original and simplified polylines.
 ///
 /// \cgalModels `PolylineSimplificationCostFunction`.
@@ -76,6 +78,7 @@ public:
 
 };
 
+  /// @}
 
 } // namespace Polyline_simplification_2
 

Polyline_simplification_2/include/CGAL/Polyline_simplification_2/Stop_above_cost_threshold.h

@@ -26,6 +26,9 @@ namespace CGAL {
 namespace Polyline_simplification_2
 {
 
+/// \addtogroup PkgPolylineSimplification2Classes
+/// @{
+
 /// This class is a stop predicate returning `true` when the cost for 
 /// simplifying a vertex is smaller than a certain threshold.
 ///
@@ -54,6 +57,7 @@ private:
   double mThres ;
 };
 
+  /// @}
 } // namespace Polyline_simplification_2
 
 } //namespace CGAL

Polyline_simplification_2/include/CGAL/Polyline_simplification_2/Stop_below_count_ratio_threshold.h

@@ -26,6 +26,8 @@ namespace CGAL {
 namespace Polyline_simplification_2
 {
 
+/// \addtogroup PkgPolylineSimplification2Classes
+/// @{
 /// This class is a stop predicate returning `true` when the percentage 
 /// of remaning vertices is smaller than a certain threshold.
 ///
@@ -54,6 +56,7 @@ private:
   double mThres ;
 };    
 
+  ///@}
 } // namespace Polyline_simplification_2
 
 } //namespace CGAL

Polyline_simplification_2/include/CGAL/Polyline_simplification_2/Stop_below_count_threshold.h

@@ -25,6 +25,9 @@ namespace CGAL {
 namespace Polyline_simplification_2
 {
 
+/// \addtogroup PkgPolylineSimplification2Classes
+/// @{
+
 /// This class is a stop predicate returning `true` when the number of 
 /// vertices is smaller than a certain threshold.
 ///
@@ -52,7 +55,7 @@ private:
   
   std::size_t mThres ;
 };    
-
+  /// @}
 } // namespace Polyline_simplification_2
 
 } //namespace CGAL

Polyline_simplification_2/include/CGAL/Polyline_simplification_2/mark_vertices_unremovable.h

@@ -27,7 +27,9 @@ class Polyline_constrained_triangulation_2;
 
 namespace Polyline_simplification_2 {
 
-// Fix the leftmost, rightmost, topmost and bottommost vertex of each polyine.
+/// \addtogroup PkgPolylineSimplification2Functions
+/// @{
+/// Fix the leftmost, rightmost, topmost and bottommost vertex of each polyine.
 template <typename Tr>
 void
 mark_vertices_unremovable(CGAL::Polyline_constrained_triangulation_2<Tr>& pct,
@@ -49,7 +51,7 @@ mark_vertices_unremovable(CGAL::Polyline_constrained_triangulation_2<Tr>& pct,
 }
 
 
-// Fix the leftmost, rightmost, topmost and bottommost vertex
+/// Fix the leftmost, rightmost, topmost and bottommost vertex
 template <typename Tr>
 void
 mark_vertices_unremovable(CGAL::Polyline_constrained_triangulation_2<Tr>& pct)
@@ -65,6 +67,7 @@ mark_vertices_unremovable(CGAL::Polyline_constrained_triangulation_2<Tr>& pct)
   }
 }
 
+/// @}
 } // namespace polyline_simplification_2
 } // namespace CGAL 
 

Polyline_simplification_2/include/CGAL/Polyline_simplification_2/simplify.h

@@ -277,6 +277,12 @@ operator()()
 
   };
 
+/// \addtogroup  PkgPolylineSimplification2Functions
+/// @{
+/// Simplifies a single polygon.
+
+/// @tparam CostFunction must be a model of `PolylineSimplificationCostFunction`.
+/// @tparam StopFunction must be a model of `PolylineSimplificationStopPredicate`
 
 template <class PolygonTraits_2, class Container, class CostFunction, class StopFunction>
                   CGAL::Polygon_2<PolygonTraits_2,Container>
@@ -313,6 +319,8 @@ template <class PolygonTraits_2, class Container, class CostFunction, class Stop
 }
 
 
+/// Simplifies a single polyline in a triangulation with polylines as constraints.
+
 template <class Tr, class CostFunction, class StopFunction>
 std::size_t
 simplify(CGAL::Polyline_constrained_triangulation_2<Tr>& pct,
@@ -331,7 +339,7 @@ simplify(CGAL::Polyline_constrained_triangulation_2<Tr>& pct,
   return simplifier.number_of_removed_vertices();
 }
 
-
+/// Simplifies all polylines in a triangulation with polylines as constraints.
 template <class Tr, class CostFunction, class StopFunction>
 std::size_t
 simplify(CGAL::Polyline_constrained_triangulation_2<Tr>& pct,
@@ -351,6 +359,9 @@ simplify(CGAL::Polyline_constrained_triangulation_2<Tr>& pct,
   return simplifier.number_of_removed_vertices();
 }
 
+///@}
+
+
 } // namespace polyline_simplification_2
 } // namespace CGAL 
 #endif