issue CGAL#7395 Improvement of layout of model relations

Consistent implementation for the `AABB_tree` in respect to `Has Model` and `Is Model Of`
albert-github · Jul 5, 2023 · c0db92d · c0db92d
1 parent 68813c5
commit c0db92d
Show file tree

Hide file tree

Showing 17 changed files with 48 additions and 25 deletions.
diff --git a/AABB_tree/doc/AABB_tree/Concepts/AABBGeomTraits.h b/AABB_tree/doc/AABB_tree/Concepts/AABBGeomTraits.h
@@ -11,7 +11,7 @@ and the primitives stored in the AABB tree.
 
 \cgalRefines{SearchGeomTraits_3}
 
-\cgalHasModel All models of the concept `Kernel`
+\cgalHasModelsBare{All models of the concept `Kernel`}
 
 \sa `CGAL::AABB_traits<AABBGeomTraits,AABBPrimitive>`
 \sa `CGAL::AABB_tree<AABBTraits>`

diff --git a/AABB_tree/doc/AABB_tree/Concepts/AABBPrimitive.h b/AABB_tree/doc/AABB_tree/Concepts/AABBPrimitive.h
@@ -12,11 +12,12 @@ The concept `AABBPrimitive` describes the requirements for the primitives stored
 
 The `Primitive` type can be, e.g., a wrapper around a `Handle`. Assume for instance that the input objects are the triangle faces of a mesh stored as a `CGAL::Polyhedron_3`. The `Datum` would be a `Triangle_3` and the `Id` would be a polyhedron `Face_handle`. Method `datum()` can return either a `Triangle_3` constructed on the fly from the face handle or a `Triangle_3` stored internally. This provides a way for the user to trade memory for efficiency.
 
-\cgalHasModel `CGAL::AABB_primitive<Id,ObjectPropertyMap,PointPropertyMap,Tag_false,CacheDatum>`
-\cgalHasModel `CGAL::AABB_segment_primitive<Iterator,CacheDatum>`
-\cgalHasModel `CGAL::AABB_triangle_primitive<Iterator,CacheDatum>`
-\cgalHasModel `CGAL::AABB_halfedge_graph_segment_primitive<HalfedgeGraph,VertexPointPMap,Tag_false,CacheDatum>`
-\cgalHasModel `CGAL::AABB_face_graph_triangle_primitive<FaceGraph,VertexPointPMap,Tag_false,CacheDatum>`
+\cgalHasModelsBegin CGAL::AABB_primitive<Id,ObjectPropertyMap,PointPropertyMap,Tag_false,CacheDatum>
+\cgalHasModels CGAL::AABB_segment_primitive<Iterator,CacheDatum>
+\cgalHasModels CGAL::AABB_triangle_primitive<Iterator,CacheDatum>
+\cgalHasModels CGAL::AABB_halfedge_graph_segment_primitive<HalfedgeGraph,VertexPointPMap,Tag_false,CacheDatum>
+\cgalHasModels CGAL::AABB_face_graph_triangle_primitive<FaceGraph,VertexPointPMap,Tag_false,CacheDatum>
+\cgalHasModelsEnd
 */
 
 class AABBPrimitive {

diff --git a/AABB_tree/doc/AABB_tree/Concepts/AABBPrimitiveWithSharedData.h b/AABB_tree/doc/AABB_tree/Concepts/AABBPrimitiveWithSharedData.h
@@ -21,9 +21,10 @@ The `Datum` would be a `Triangle_3` and the `Id` a `std::size_t`. The shared dat
 `std::vector<Triangle_3>`.
 The method `datum(const Shared_data&)` then returns a triangle from the vector.
 
-\cgalHasModel `CGAL::AABB_primitive<Id,ObjectPropertyMap,PointPropertyMap,Tag_true,CacheDatum>`
-\cgalHasModel `CGAL::AABB_halfedge_graph_segment_primitive<HalfedgeGraph,VertexPointPMap,Tag_true,CacheDatum>`
-\cgalHasModel `CGAL::AABB_face_graph_triangle_primitive<FaceGraph,VertexPointPMap,Tag_true,CacheDatum>`
+\cgalHasModelsBegin CGAL::AABB_primitive<Id,ObjectPropertyMap,PointPropertyMap,Tag_true,CacheDatum>
+\cgalHasModels CGAL::AABB_halfedge_graph_segment_primitive<HalfedgeGraph,VertexPointPMap,Tag_true,CacheDatum>
+\cgalHasModels CGAL::AABB_face_graph_triangle_primitive<FaceGraph,VertexPointPMap,Tag_true,CacheDatum>
+\cgalHasModelsEnd
 */
 
 class AABBPrimitiveWithSharedData {

diff --git a/AABB_tree/doc/AABB_tree/Concepts/AABBRayIntersectionGeomTraits.h b/AABB_tree/doc/AABB_tree/Concepts/AABBRayIntersectionGeomTraits.h
@@ -9,7 +9,7 @@ define the Intersection_distance functor.
 
 \cgalRefines{AABBGeomTraits}
 
-\cgalHasModel All models of the concept `Kernel`
+\cgalHasModelsBare{All models of the concept `Kernel`}
 
 \sa `CGAL::AABB_traits<AABBGeomTraits,AABBPrimitive>`
 \sa `CGAL::AABB_tree<AABBTraits>`

diff --git a/AABB_tree/doc/AABB_tree/Concepts/AABBRayIntersectionTraits.h b/AABB_tree/doc/AABB_tree/Concepts/AABBRayIntersectionTraits.h
@@ -7,7 +7,8 @@ The concept `AABBRayIntersectionTraits` is a refinement of the concept
 `AABBTraits` it also requires function objects to calculate the
 distance of an intersection along a ray.
 
-\cgalHasModel `CGAL::AABB_traits<AABBGeomTraits,AABBPrimitive>`
+\cgalHasModelsBegin CGAL::AABB_traits<AABBGeomTraits,AABBPrimitive>
+\cgalHasModelsEnd
 
 \sa `CGAL::AABB_tree<AABBTraits>`
 \sa `AABBPrimitive`

diff --git a/AABB_tree/doc/AABB_tree/Concepts/AABBTraits.h b/AABB_tree/doc/AABB_tree/Concepts/AABBTraits.h
@@ -5,7 +5,8 @@
 
 The concept `AABBTraits` provides the geometric primitive types and methods for the class `CGAL::AABB_tree<AABBTraits>`.
 
-\cgalHasModel `CGAL::AABB_traits<AABBGeomTraits,AABBPrimitive>`
+\cgalHasModelsBegin CGAL::AABB_traits<AABBGeomTraits,AABBPrimitive>
+\cgalHasModelsEnd
 
 \cgalRefines{SearchGeomTraits_3}
 

diff --git a/AABB_tree/include/CGAL/AABB_face_graph_triangle_primitive.h b/AABB_tree/include/CGAL/AABB_face_graph_triangle_primitive.h
@@ -33,7 +33,7 @@ namespace CGAL {
  * while the AABB tree holding the primitive is in use.
  * The triangle type of the primitive (`Datum`) is `CGAL::Kernel_traits< boost::property_traits< VertexPointPMap >::%value_type >::%Kernel::Triangle_3`.
  *
- * \cgalModels `AABBPrimitiveWithSharedData`
+ * \cgalModels{AABBPrimitiveWithSharedData}
  *
  *\tparam FaceGraph is a model of the face graph concept.
  *\tparam VertexPointPMap  is a property map with `boost::graph_traits<FaceGraph>::%vertex_descriptor`

diff --git a/AABB_tree/include/CGAL/AABB_halfedge_graph_segment_primitive.h b/AABB_tree/include/CGAL/AABB_halfedge_graph_segment_primitive.h
@@ -41,8 +41,8 @@ namespace CGAL {
  * of `VertexPointPMap` (using the `Kernel_traits` mechanism).
  * The segment type of the primitive (`Datum`) is `CGAL::Kernel_traits< boost::property_traits< VertexPointPMap >::%value_type >::%Kernel::Segment_3`.
  *
- * \cgalModels `AABBPrimitive` if `OneHalfedgeGraphPerTree` is `CGAL::Tag_false`,
- *    and `AABBPrimitiveWithSharedData` if `OneHalfedgeGraphPerTree` is `CGAL::Tag_true`.
+ * \cgalModelsBare{AABBPrimitive if `OneHalfedgeGraphPerTree` is `CGAL::Tag_false`,
+ *                 AABBPrimitiveWithSharedData if `OneHalfedgeGraphPerTree` is `CGAL::Tag_true`}
  *
  * \tparam HalfedgeGraph is a model of the halfedge graph concept.
  *   as key type and a \cgal Kernel `Point_3` as value type.

diff --git a/AABB_tree/include/CGAL/AABB_polyhedron_segment_primitive.h b/AABB_tree/include/CGAL/AABB_polyhedron_segment_primitive.h
@@ -42,7 +42,7 @@ namespace CGAL {
     /// AABB tree is built should not be deleted while the AABB tree
     /// is in use.
     ///
-    /// \cgalModels `AABBPrimitive`
+    /// \cgalModels{AABBPrimitive}
     /// \tparam GeomTraits must provide a \c %Point_3
     /// type, used as \c Point, and a \c %Segment_3 type, used as \c
     /// Datum and constructible from two arguments of type \c

diff --git a/AABB_tree/include/CGAL/AABB_polyhedron_triangle_primitive.h b/AABB_tree/include/CGAL/AABB_polyhedron_triangle_primitive.h
@@ -35,7 +35,7 @@ namespace CGAL {
     /// the polyhedron from which the AABB tree is built should not be
     /// deleted while the AABB tree is in use.
     ///
-    /// \cgalModels `AABBPrimitive`
+    /// \cgalModels{AABBPrimitive}
     /// \tparam GeomTraits must provides a \c %Point_3
     /// type, used as \c Point, and a \c %Triangle_3 type, used as \c
     /// Datum and constructible from three arguments of type \c

diff --git a/AABB_tree/include/CGAL/AABB_primitive.h b/AABB_tree/include/CGAL/AABB_primitive.h
@@ -53,8 +53,8 @@ struct AABB_primitive_base
  * The two property maps which are template parameters of the class enable to get the datum and the reference point of
  * the primitive from the identifier. The last template parameter controls whether the primitive class holds a copy of the datum.
  *
- * \cgalModels `AABBPrimitive` if `ExternalPropertyMaps` is `CGAL::Tag_false`.
- * \cgalModels `AABBPrimitiveWithSharedData` if `ExternalPropertyMaps` is `CGAL::Tag_true`.
+ * \cgalModelsBare{AABBPrimitive if `ExternalPropertyMaps` is `CGAL::Tag_false`,
+ *                 AABBPrimitiveWithSharedData if `ExternalPropertyMaps` is `CGAL::Tag_true`}
  *
  * \tparam ObjectPropertyMap is a model of `ReadablePropertyMap` with `Id` as
  *           `key_type`. It must be a model of `CopyConstructible`, `DefaultConstructible`, and `CopyAssignable`.

diff --git a/AABB_tree/include/CGAL/AABB_segment_primitive.h b/AABB_tree/include/CGAL/AABB_segment_primitive.h
@@ -54,7 +54,7 @@ namespace internal {
  * The iterator from which the primitive is built should not be invalided
  * while the AABB tree holding the primitive is in use.
  *
- * \cgalModels `AABBPrimitive`
+ * \cgalModels{AABBPrimitive}
  *
  * \tparam GeomTraits is a traits class providing the nested type `Point_3` and `Segment_3`.
  *         It also provides the functor `Construct_source_3` that has an operator taking a `Segment_3`

diff --git a/AABB_tree/include/CGAL/AABB_traits.h b/AABB_tree/include/CGAL/AABB_traits.h
@@ -149,9 +149,8 @@ class AABB_tree;
 /// computations, and it handles points as query type for distance
 /// queries.
 ///
-/// \cgalModels AABBTraits
-/// \cgalModels AABBRayIntersectionTraits
-
+/// \cgalModels{AABBTraits,AABBRayIntersectionTraits}
+///
 /// \tparam GeomTraits must  be a model of the concept \ref AABBGeomTraits,
 /// and provide the geometric types as well as the intersection tests and computations.
 /// \tparam Primitive provide the type of primitives stored in the AABB_tree.

diff --git a/AABB_tree/include/CGAL/AABB_triangle_primitive.h b/AABB_tree/include/CGAL/AABB_triangle_primitive.h
@@ -55,7 +55,7 @@ namespace internal {
  * The iterator from which the primitive is built should not be invalided
  * while the AABB tree holding the primitive is in use.
  *
- * \cgalModels `AABBPrimitive`
+ * \cgalModels{AABBPrimitive}
  *
  * \tparam GeomTraits is a traits class providing the nested type `Point_3` and `Triangle_3`.
  *         It also provides the functor `Construct_vertex_3` that has an operator taking a `Triangle_3`

diff --git a/AABB_tree/include/CGAL/AABB_triangulation_3_triangle_primitive.h b/AABB_tree/include/CGAL/AABB_triangulation_3_triangle_primitive.h
@@ -28,7 +28,7 @@ namespace CGAL {
     // the TriangleMesh from which the AABB tree is built should not be
     // deleted while the AABB tree is in use.
     //
-    // \cgalModels `AABBPrimitive`
+    // \cgalModels{AABBPrimitive}
     // \tparam GeomTraits must provides a \c %Point_3
     // type, used as \c Point, and a \c %Triangle_3 type, used as \c
     // Datum and constructible from three arguments of type \c

diff --git a/Documentation/doc/resources/1.8.13/BaseDoxyfile.in b/Documentation/doc/resources/1.8.13/BaseDoxyfile.in
@@ -136,8 +136,18 @@ ALIASES                = "cgal=%CGAL" \
                          "cgalRefinesBare{1}=<dl><dt>@cgalRefines</dt><dd>\1</dd></dl>" \
                          "cgalRefinesBare{2}=<dl><dt>@cgalRefines</dt><dd>@c \1</dd><dt></dt><dd>\2</dd></dl>" \
                          "cgalModels=\xrefitem models \"Is Model Of\" \"Is Model Relationships\"" \
+                         "cgalModelsHeader=Is Model Of" \
+                         "cgalModels{1}=<dl><dt>@cgalModelsHeader</dt><dd>@c \1</dd></dl>" \
+                         "cgalModels{2}=<dl><dt>@cgalModelsHeader</dt><dd>@c \1</dd><dt></dt><dd>@c \2</dd></dl>" \
+                         "cgalModelsBare{1}=<dl><dt>@cgalModelsHeader</dt><dd>\1</dd></dl>" \
+                         "cgalModelsBare{2}=<dl><dt>@cgalModelsHeader</dt><dd>@c \1</dd><dt></dt><dd>\2</dd></dl>" \
                          "cgalGeneralizes=\xrefitem generalizes \"Generalizes\" \"Generalization Relationships\"" \
                          "cgalHasModel=\xrefitem hasModels \"Has Models\" \"Has Model Relationships\"" \
+                         "cgalHasModelsHeader=Has Models" \
+                         "cgalHasModelsBegin=<dl><dt>@cgalHasModelsHeader</dt><dd>`" \
+                         "cgalHasModels=`</dd><dt></dt><dd>`" \
+                         "cgalHasModelsEnd=`</dd></dl>" \
+                         "cgalHasModelsBare{1}=<dl><dt>@cgalHasModels</dt><dd>\1</dd></dl>" \
                          "cgalDebugBegin=\htmlonly <div class=\"CGALDebug\"> <div>Debugging Support</div> \endhtmlonly \n" \
                          "cgalDebugEnd=\htmlonly </div> \endhtmlonly" \
                          "cgalDebugFunction=This is a function for debugging purpose." \

diff --git a/Documentation/doc/resources/1.9.6/BaseDoxyfile.in b/Documentation/doc/resources/1.9.6/BaseDoxyfile.in
@@ -145,8 +145,18 @@ ALIASES                = "cgal=%CGAL" \
                          "cgalRefinesBare{1}=<dl><dt>@cgalRefines</dt><dd>\1</dd></dl>" \
                          "cgalRefinesBare{2}=<dl><dt>@cgalRefines</dt><dd>@c \1</dd><dt></dt><dd>\2</dd></dl>" \
                          "cgalModels=\xrefitem models \"Is Model Of\" \"Is Model Relationships\"" \
+                         "cgalModelsHeader=Is Model Of" \
+                         "cgalModels{1}=<dl><dt>@cgalModelsHeader</dt><dd>@c \1</dd></dl>" \
+                         "cgalModels{2}=<dl><dt>@cgalModelsHeader</dt><dd>@c \1</dd><dt></dt><dd>@c \2</dd></dl>" \
+                         "cgalModelsBare{1}=<dl><dt>@cgalModelsHeader</dt><dd>\1</dd></dl>" \
+                         "cgalModelsBare{2}=<dl><dt>@cgalModelsHeader</dt><dd>@c \1</dd><dt></dt><dd>\2</dd></dl>" \
                          "cgalGeneralizes=\xrefitem generalizes \"Generalizes\" \"Generalization Relationships\"" \
                          "cgalHasModel=\xrefitem hasModels \"Has Models\" \"Has Model Relationships\"" \
+                         "cgalHasModelsHeader=Has Models" \
+                         "cgalHasModelsBegin=<dl><dt>@cgalHasModelsHeader</dt><dd>`" \
+                         "cgalHasModels=`</dd><dt></dt><dd>`" \
+                         "cgalHasModelsEnd=`</dd></dl>" \
+                         "cgalHasModelsBare{1}=<dl><dt>@cgalHasModelsHeader</dt><dd>\1</dd></dl>" \
                          "cgalDebugBegin=\htmlonly[block] <div class=\"CGALDebug\"> <div>Debugging Support</div> \endhtmlonly ^^" \
                          "cgalDebugEnd=\htmlonly[block] </div> \endhtmlonly" \
                          "cgalDebugFunction=This is a function for debugging purpose." \