From 91e2e24d3090f908d401c7f89d03b7f5ba9ee920 Mon Sep 17 00:00:00 2001
From: Andreas Fabri <andreas.fabri@geometryfactory.com>
Date: Mon, 11 Apr 2022 16:43:42 +0100
Subject: [PATCH] Add documentation

---
 .../Concepts/PMPHolefillingVisitor.h          | 49 +++++++++++++++++++
 .../triangulate_hole.h                        | 20 ++++++--
 2 files changed, 66 insertions(+), 3 deletions(-)
 create mode 100644 Polygon_mesh_processing/doc/Polygon_mesh_processing/Concepts/PMPHolefillingVisitor.h

diff --git a/Polygon_mesh_processing/doc/Polygon_mesh_processing/Concepts/PMPHolefillingVisitor.h b/Polygon_mesh_processing/doc/Polygon_mesh_processing/Concepts/PMPHolefillingVisitor.h
new file mode 100644
index 00000000000..6f49c4fbec6
--- /dev/null
+++ b/Polygon_mesh_processing/doc/Polygon_mesh_processing/Concepts/PMPHolefillingVisitor.h
@@ -0,0 +1,49 @@
+/// \ingroup PkgPolygonMeshProcessingConcepts
+/// \cgalConcept
+///
+/// The concept `PMPHolefillingVisitor` defines the requirements for the visitor
+/// used in \link PMP_hole_filling_grp hole-filling-related functions \endlink to track
+/// the creation of new faces and new edges.
+/// The hole filling may use a 2D constrained triangulation
+/// for almost planar holes.  If that is not appropriate or fails it
+/// may use an algorithm with at most quadratic running time. If that fails
+/// it uses an algorithm with cubic running time.
+///
+/// \cgalRefines `CopyConstructible`
+/// \cgalHasModel `CGAL::Polygon_mesh_processing::Holefilling::Default_visitor`.
+
+class PMPHolefillingVisitor{
+public:
+
+  /// called when the planar hole filling algorithm starts.
+  void start_planar_phase() const;
+
+  /// called when the  planar hole filling algorithm stops.
+  /// @param success `true` when the hole could be filled in this phase.
+  void end_planar_phase(bool success) const;
+
+  /// called when the algorithm with quadratic running time starts.
+  /// @param N the upperbound on the number of steps
+  void start_quadratic_phase(int N) const;
+
+    /// called at each step. There may be less than `N` calls as this
+    /// is an upperbound.
+  void quadratic_step() const;
+
+  /// called when the algorithm with quadratic running time ends.
+    /// @param success `true` when the hole could be filled in this
+    /// phase.
+  void end_quadratic_phase(bool success) const;
+
+  /// called when the algorithm with cubic running time starts.
+    /// @param N the upperbound on the number of steps
+  void start_cubic_phase(int N) const;
+
+  /// called at each step. This will be called `N` times.
+  void cubic_step() const;
+
+  /// called when the algorithm with cubic running time ends.
+  void end_cubic_phase() const;
+
+
+};
diff --git a/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/triangulate_hole.h b/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/triangulate_hole.h
index bf69f1e6e0c..759aa945777 100644
--- a/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/triangulate_hole.h
+++ b/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/triangulate_hole.h
@@ -34,8 +34,15 @@
 namespace CGAL {
 
 namespace Polygon_mesh_processing {
+/** \ingroup PMP_hole_filling_grp
+ *  Default hole filling visitor model of `PMPHolefillingVisitor`.
+ *  All of its functions have an empty body. This class can be used as a
+ *  base class if only some of the functions of the concept require to be
+ *  overridden.
+ */
+  namespace Hole_filling {
 
-    struct Hole_fill_visitor{
+    struct Default_visitor{
 
       void start_planar_phase() const
       {}
@@ -63,6 +70,7 @@ namespace Polygon_mesh_processing {
 
 
     };
+  } // namespace Hole_filling
 
   /*!
   \ingroup PMP_hole_filling_grp
@@ -141,6 +149,12 @@ namespace Polygon_mesh_processing {
                       otherwise nothing will be done.}
     \cgalParamNEnd
 
+    \cgalParamNBegin{visitor}
+      \cgalParamDescription{a visitor used to track the progress made
+      in the algorithm}
+      \cgalParamType{}
+    \cgalParamNEnd
+
   \cgalNamedParamsEnd
 
   @return `out`
@@ -206,7 +220,7 @@ namespace Polygon_mesh_processing {
       CGAL_assertion(max_squared_distance >= typename GeomTraits::FT(0));
     }
 
-    Hole_fill_visitor default_visitor;
+    Hole_filling::Default_visitor default_visitor;
 
     return internal::triangulate_hole_polygon_mesh(
       pmesh,
@@ -568,7 +582,7 @@ bool use_dt3 =
     typedef typename std::iterator_traits<InIterator>::value_type Point;
     typedef typename CGAL::Kernel_traits<Point>::Kernel Kernel;
 
-    Hole_fill_visitor default_visitor;
+    Hole_filling::Default_visitor default_visitor;
 
 #ifndef CGAL_HOLE_FILLING_DO_NOT_USE_CDT2
     if (use_cdt)