From a001ee036a38e4449df6c9df8750b42269431b7f Mon Sep 17 00:00:00 2001
From: Laurent Rineau <laurent.rineau@cgal.org>
Date: Mon, 16 Jun 2025 15:04:20 +0200
Subject: [PATCH] better snippets for triangulation()

---
 ...g_constrained_Delaunay_triangulation_3.cpp | 20 +++++++++++++++----
 ...h_constrained_Delaunay_triangulation_3.cpp |  2 --
 ...ing_constrained_Delaunay_triangulation_3.h | 10 ++++++++--
 3 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/Constrained_triangulation_3/examples/Constrained_triangulation_3/conforming_constrained_Delaunay_triangulation_3.cpp b/Constrained_triangulation_3/examples/Constrained_triangulation_3/conforming_constrained_Delaunay_triangulation_3.cpp
index 6cf56cc7bc7..8b1078c061c 100644
--- a/Constrained_triangulation_3/examples/Constrained_triangulation_3/conforming_constrained_Delaunay_triangulation_3.cpp
+++ b/Constrained_triangulation_3/examples/Constrained_triangulation_3/conforming_constrained_Delaunay_triangulation_3.cpp
@@ -1,10 +1,11 @@
 #include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
 #include <CGAL/IO/polygon_mesh_io.h>
 #include <CGAL/Surface_mesh.h>
-#include <CGAL/draw_constrained_triangulation_3.h>
 #include <CGAL/make_conforming_constrained_Delaunay_triangulation_3.h>
 #include <CGAL/IO/write_MEDIT.h>
 
+#include <cassert>
+
 using K = CGAL::Exact_predicates_inexact_constructions_kernel;
 
 int main(int argc, char* argv[])
@@ -22,16 +23,27 @@ int main(int argc, char* argv[])
 
   auto ccdt = CGAL::make_conforming_constrained_Delaunay_triangulation_3(mesh);
 
+  //! [use of ccdt.triangulation()]
   std::cout << "Number of vertices in the CDT: "
-            << ccdt.triangulation().number_of_vertices() << '\n'
-            << "Number of constrained facets in the CDT: "
+            << ccdt.triangulation().number_of_vertices() << '\n';
+  //! [use of ccdt.triangulation()]
+  std::cout << "Number of constrained facets in the CDT: "
             << ccdt.number_of_constrained_facets() << '\n';
 
   std::ofstream ofs(argc > 2 ? argv[2] : "out.mesh");
   ofs.precision(17);
   CGAL::IO::write_MEDIT(ofs, ccdt);
 
-  CGAL::draw(ccdt);
+  //! [move ccdt to tr]
+  auto tr = std::move(ccdt).triangulation();
+  // Now `tr` is a valid `CGAL::Triangulation_3` object that can be used for further processing.
+  // and the triangulation of `ccdt` is empty.
+  std::cout << "Number of vertices in the triangulation `tr`: "
+            << tr.number_of_vertices() << '\n';
+  std::cout << "Number of vertices in `ccdt`: "
+            << ccdt.triangulation().number_of_vertices() << '\n';
+  assert(ccdt.triangulation().number_of_vertices() == 0);
+  //! [move ccdt to tr]
 
   return EXIT_SUCCESS;
 }
diff --git a/Constrained_triangulation_3/examples/Constrained_triangulation_3/remesh_constrained_Delaunay_triangulation_3.cpp b/Constrained_triangulation_3/examples/Constrained_triangulation_3/remesh_constrained_Delaunay_triangulation_3.cpp
index d13172de94d..e87918ee70b 100644
--- a/Constrained_triangulation_3/examples/Constrained_triangulation_3/remesh_constrained_Delaunay_triangulation_3.cpp
+++ b/Constrained_triangulation_3/examples/Constrained_triangulation_3/remesh_constrained_Delaunay_triangulation_3.cpp
@@ -58,12 +58,10 @@ int main(int argc, char* argv[])
   Constraints_set constraints;
   Constraints_pmap constraints_pmap(constraints);
 
-  //! [move ccdt to tr]
   namespace np = CGAL::parameters;
   namespace Tet_remesh = CGAL::Tetrahedral_remeshing;
   Tr tr = Tet_remesh::get_remeshing_triangulation(std::move(ccdt),
                                                   np::edge_is_constrained_map(constraints_pmap));
-  //! [move ccdt to tr]
   std::cout << "Number of vertices in tr: " << tr.number_of_vertices() << std::endl;
 
   CGAL::tetrahedral_isotropic_remeshing(tr,
diff --git a/Constrained_triangulation_3/include/CGAL/Conforming_constrained_Delaunay_triangulation_3.h b/Constrained_triangulation_3/include/CGAL/Conforming_constrained_Delaunay_triangulation_3.h
index 2b76a96cb91..60029fab9ce 100644
--- a/Constrained_triangulation_3/include/CGAL/Conforming_constrained_Delaunay_triangulation_3.h
+++ b/Constrained_triangulation_3/include/CGAL/Conforming_constrained_Delaunay_triangulation_3.h
@@ -855,7 +855,11 @@ public:
     * \brief returns a const reference to the underlying triangulation.
     *
     * This allows the use of all non-modifying functions of the base triangulation.
-    * See the other overload for a way to move the triangulation out of this object and then modify it.
+    * See the other overload for a way to move the triangulation out of this object and then modify
+    * it.
+    *
+    * Example usage:
+    * \snippet[trimleft] conforming_constrained_Delaunay_triangulation_3.cpp use of ccdt.triangulation()
     */
   const Triangulation& triangulation() const& {
     return cdt_impl;
@@ -865,8 +869,10 @@ public:
     * \brief moves and returns the underlying triangulation, then clears the object.
     *
     * This function allows the underlying triangulation to be moved out of this object.
+    *
     * Example usage:
-    * \snippet{trimleft} remesh_constrained_Delaunay_triangulation_3.cpp move ccdt to tr
+    * \snippet[trimleft] conforming_constrained_Delaunay_triangulation_3.cpp move ccdt to tr
+    *
     * After calling this function, `ccdt` will be empty and `tr` will be move-constructed from the underlying triangulation, avoiding any copy.
     *
     * \note This function is available only when the object is an rvalue.