From 161f1b83d4d5ccf2b7a4f4e3fa1c43fab00a96b9 Mon Sep 17 00:00:00 2001
From: Andreas Fabri <andreas.fabri@geometryfactory.com>
Date: Fri, 10 Mar 2023 16:43:52 +0000
Subject: [PATCH] Surface_mesh: Document join()

---
 .../examples/Surface_mesh/sm_properties.cpp   | 25 +++++++++++++++++--
 .../include/CGAL/Surface_mesh/Surface_mesh.h  |  4 +++
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/Surface_mesh/examples/Surface_mesh/sm_properties.cpp b/Surface_mesh/examples/Surface_mesh/sm_properties.cpp
index 6cb870f6194..d771ad492fd 100644
--- a/Surface_mesh/examples/Surface_mesh/sm_properties.cpp
+++ b/Surface_mesh/examples/Surface_mesh/sm_properties.cpp
@@ -2,6 +2,7 @@
 
 #include <CGAL/Simple_cartesian.h>
 #include <CGAL/Surface_mesh.h>
+#include <CGAL/boost/graph/generators.h>
 
 typedef CGAL::Simple_cartesian<double> K;
 typedef CGAL::Surface_mesh<K::Point_3> Mesh;
@@ -25,7 +26,7 @@ int main()
   // give each vertex a name, the default is empty
   Mesh::Property_map<vertex_descriptor,std::string> name;
   bool created;
-  boost::tie(name, created) = m.add_property_map<vertex_descriptor,std::string>("v:name","");
+  boost::tie(name, created) = m.add_property_map<vertex_descriptor,std::string>("v:name","m1");
   assert(created);
   // add some names to the vertices
   name[v0] = "hello";
@@ -51,14 +52,34 @@ int main()
     std::cout << name[vd] << " @ " << location[vd] << std::endl;
   }
 
+  Mesh m2;
+  CGAL::make_triangle(K::Point_3(0,0,1), K::Point_3(1,0,1),K::Point_3(0,1,1), m2);
+
+  m2.add_property_map<vertex_descriptor,std::string>("v:name","m2");
+  Mesh::Property_map<vertex_descriptor,int> index;
+  index = m2.add_property_map<vertex_descriptor,int>("v:index",-1).first;
+  int i = 0;
+  for (auto v : vertices(m2)) {
+      index[v] = i++;
+  }
+
+  std::cout << "properties of m1:" << std::endl;
   std::vector<std::string> props = m.properties<vertex_descriptor>();
   for(std::string p : props){
     std::cout << p << std::endl;
   }
 
+  m.join(m2);
+  std::cout << "properties of m1 after join:" << std::endl;
+  for(std::string p : m.properties<vertex_descriptor>()){
+    std::cout << p << std::endl;
+  }
+
+  for (auto v : vertices(m)) {
+    std::cout << name[v] << std::endl;
+  }
   // delete the string property again
   m.remove_property_map(name);
 
   return 0;
 }
-
diff --git a/Surface_mesh/include/CGAL/Surface_mesh/Surface_mesh.h b/Surface_mesh/include/CGAL/Surface_mesh/Surface_mesh.h
index ea1f3f048f9..47232cbabd5 100644
--- a/Surface_mesh/include/CGAL/Surface_mesh/Surface_mesh.h
+++ b/Surface_mesh/include/CGAL/Surface_mesh/Surface_mesh.h
@@ -1215,6 +1215,10 @@ public:
         fprops_.resize(nfaces);
     }
 
+  /// copies the simplices from `other`, and copies values of
+  /// properties that already exist under the same name in `*this`.
+  /// In case `*this` has a property that does not exist in `other`
+  /// the copied simplices get the default value of the property.
   bool join(const Surface_mesh& other)
   {
     // increase capacity