Start to document

BGL/doc/BGL/BGL.txt

@@ -416,6 +416,31 @@ incident to a given face, and all halfedges having a given vertex as target.
 These types  are not part of the concept `HalfedgeGraph`, but they
 are class templates that work for any model of this concept.
 
+
+\subsection BGLProperties Properties and Dynamic Properties
+
+As the concepts `FaceGraph`  adds the notion of halfedges and faces,
+as well as a geometric embedding of the vertices, we have to add
+property tags such as `face_index_t` and `vertex_point_t`.
+
+We further add <em>dynamic property maps</em> that enable the user
+to add properties to vertices, halfedges, edges, and faces on the fly.
+For mesh classes such as `Surface_mesh` and meshes from OpenMesh
+this creates the internal property maps offered by these classes.
+For `Polyhedron_3` this creates an `unordered_map`.
+
+Dynamic property tags such as `vertex_property_t` are a generalization of
+`boost::vertex_index_t`, as they have a template parameter for the
+value type of the dynamic property map.
+
+Just as `boost::property_map<G>::type` provides support for obtaining the
+type of a property map for a vertex index, or a vertex point, the class
+`dynamic_property_map` provides support for obtaining the type
+of a dynamic property map for a given graph type and a dynamic property tag.
+
+\cgalExample{Property_map/dynamic_properties.cpp}
+
+
 \subsection BGLEulerOperations Euler Operations
 
 There are two categories of mutating operations. The first category comprises

BGL/doc/BGL/CGAL/boost/graph/properties.h

@@ -36,4 +36,56 @@ enum vertex_point_t { vertex_point };
 
 
 /// @}
-}
+} // namespace boost
+
+namespace CGAL {
+
+
+/// @{
+
+  /// \ingroup PkgBGLPropertiesDynamic
+/// Dynamic vertex property tag
+/// \tparam T the value type of the vertex property
+template <typename T>
+struct vertex_property_t
+{
+  /// \param s the name of the property
+  vertex_property_t(const std::string s);
+};
+
+  /// \ingroup PkgBGLPropertiesDynamic
+/// Dynamic halfedge property tag
+/// \tparam T the value type of the halfedge property
+template <typename T>
+struct halfedge_property_t
+{
+  /// \param s the name of the property
+  halfedge_property_t(const std::string s);
+};
+  
+/// \ingroup PkgBGLPropertiesDynamic
+/// Helper class to obtain the type of the dynamic property map for a graph type and a dynamic property tag
+/// \tparam G must be a model of
+/// \tparam D must be a model of DynamicPropertyTag
+template <typename G, typename D>
+struct dynamic_property_map<G, D>
+{
+  /// The type of the dynamic property map
+  typedef unspecified_type type;
+};
+
+/// \ingroup PkgBGLPropertiesDynamic
+/// adds a dynamic property map to `g`
+template <typename T, typename G>
+typename dynamic_property_map<G,vertex_property_t<T> >::const_type
+add_property(vertex_property_t<T> prop, const G& g);
+
+  
+/// \ingroup PkgBGLPropertiesDynamic
+/// removes a dynamic property map assocated to `g`
+template<typename G, typename D>
+void remove_property(D dpm,
+                     const G&);
+
+/// @}
+} // namespace CGAL

BGL/doc/BGL/Doxyfile.in

@@ -17,6 +17,7 @@ INPUT += ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/boost/graph/Euler_operations.h \
 EXAMPLE_PATH               =  ${CGAL_Surface_mesh_skeletonization_EXAMPLE_DIR} \
                               ${CGAL_Surface_mesh_segmentation_EXAMPLE_DIR} \
                               ${CGAL_Polygon_mesh_processing_EXAMPLE_DIR} \
+                              ${CGAL_Property_map_EXAMPLE_DIR} \
                               ${CGAL_BGL_EXAMPLE_DIR}
 
 ALIASES +=  "bgllink{1}=<a href=\"http://www.boost.org/libs/graph/doc/\1.html\"><code>\1</code></a>"

BGL/doc/BGL/PackageDescription.txt

@@ -184,6 +184,9 @@ Valid Expression  |  returns                                   | Description
 /// \defgroup PkgBGLProperties Properties
 /// \ingroup PkgBGL
 
+/// \defgroup PkgBGLPropertiesDynamic Dynamic Properties
+/// \ingroup PkgBGL
+
 /// \defgroup PkgBGLHelper Helper Classes
 /// \ingroup PkgBGL
 
@@ -202,6 +205,12 @@ Valid Expression  |  returns                                   | Description
 /// \defgroup PkgBGLEulerOperations Euler Operations
 /// \ingroup PkgBGL
 
+
+/*!
+\addtogroup PkgBGLPropertiesDynamic
+The dynamic property tags enable to associate information to simplices of a `FaceGraph` on the fly.
+*/
+
 /*!
 \addtogroup PkgBGLHelper
 Several classes that enable to store ids in vertices/halfedges/faces of a `CGAL::Polyhedron_3`, as well as adapters such as `CGAL::Dual`.

BGL/doc/BGL/examples.txt

@@ -19,4 +19,5 @@
 \example Surface_mesh_skeletonization/simple_mcfskel_example.cpp
 \example Surface_mesh_segmentation/extract_segmentation_into_mesh_example.cpp
 \example Polygon_mesh_processing/face_filtered_graph_example.cpp
+èxample Property_map/dynamic_properties.cpp
 */