Merge pull request #1096 from vissarion/fix/doc_concepts

Fix concept documentation

doc/concept/polygon.qbk

@@ -15,7 +15,7 @@
 [heading Description]
 [concept Polygon..polygon]
 
-A polygon is ['A polygon is a planar surface defined by one exterior boundary and zero or more interior boundaries] 
+A polygon is ['A polygon is a planar surface defined by one exterior boundary and zero or more interior boundaries]
 (__ogc_sf__).
 
 So the definition of a Boost.Geometry polygon differs a bit from e.g. Wiki, where a polygon does not have holes. A
@@ -27,44 +27,46 @@ polygon of Boost.Geometry is a polygon with or without holes.
 The Polygon Concept is defined as following:
 
 * there must be a specialization of `traits::tag` defining `polygon_tag` as type
-* there must be a specialization of `traits::ring_type` defining the type of its exterior ring and interior rings as type
+* there must be a specialization of `traits::ring_mutable_type` defining the mutable types of its exterior and interior rings as type
-* this type defined by `ring_type` must fulfill the [link geometry.reference.concepts.concept_ring Ring Concept]
+* there must be a specialization of `traits::ring_const_type` defining the constant types of its exterior and interior rings as type
-* there must be a specialization of `traits::interior_type` defining the type of the collection of its interior rings as type;
+* `traits::ring_mutable_type` and `traits::ring_const_type` must fulfill the [link geometry.reference.concepts.concept_ring Ring Concept]
-    this collection itself must fulfill a Boost.Range Random Access Range Concept
+* there must be a specialization of `traits::interior_mutable_type` defining the mutable type of the collection of its interior rings as type;
+* there must be a specialization of `traits::interior_const_type` defining the constant type of the collection of its interior rings as type;
+    each of these collections itself must fulfill a Boost.Range Random Access Range Concept
 * there must be a specialization of `traits::exterior_ring` with two functions named `get`, returning the exterior ring, one being const, the other being non const
 * there must be a specialization of `traits::interior_rings` with two functions named `get`, returning the interior rings, one being const, the other being non const
 
 [heading Rules]
 
-Besides the Concepts, which are checks on compile-time, there are some other 
+Besides the Concepts, which are checks on compile-time, there are some other
-rules that valid polygons must fulfill. This follows the opengeospatial rules (see link 
+rules that valid polygons must fulfill. This follows the opengeospatial rules (see link
 above).
 
 * Polygons are simple geometric objects (See also [@http://en.wikipedia.org/wiki/Simple_polygon wiki]
     but holes are allowed in __boost_geometry__ polygons).
 * If the polygons underlying `ring_type` is defined as clockwise, the exterior
-    ring must have the clockwise orientation, and any interior ring must be 
+    ring must have the clockwise orientation, and any interior ring must be
-    reversed w.r.t. the defined orientation (so: counter clockwise for clockwise exterior rings). 
+    reversed w.r.t. the defined orientation (so: counter clockwise for clockwise exterior rings).
     If the `ring_type` is defined counter clockwise, it is vice versa.
 * If the polygons underlying `ring_type` is defined as closed, all rings must be
     closed: the first point must be spatially equal to the last point.
 * The interior is a connected point set.
-* There should be no self intersections, but self tangencies (between 
+* There should be no self intersections, but self tangencies (between
     exterior/interior rings) are allowed (as long as the interior is a connected
     point set.
 * There should be no cut lines, spikes or punctures.
 * The interior rings should be located within the exterior ring. Interior rings
     may not be located within each other.
 
-The algorithms such as intersection, area, centroid, union, etc. do not check 
+The algorithms such as intersection, area, centroid, union, etc. do not check
-validity. There will be an algorithm is_valid which checks for 
+validity. There will be an algorithm is_valid which checks for
 validity against these rules, at runtime, and which can be called (by the library
 user) before.
 
 If the input is invalid, the output might be invalid too. For example: if a polygon
 which should be closed is not closed, the area will be incorrect.
 
-[heading Available Models]	
+[heading Available Models]
 * [link geometry.reference.models.model_polygon polygon]
 * a Boost.Polygon polygon_with_holes_data (requires `#include boost/geometry/geometries/adapted/boost_polygon/polygon.hpp>`)
 

doc/html/index.html

@@ -3,7 +3,7 @@
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <title>Chapter 1. Geometry</title>
 <link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
 <link rel="home" href="index.html" title="Chapter 1. Geometry">
 <link rel="next" href="geometry/introduction.html" title="Introduction">
 </head>
@@ -150,7 +150,7 @@
 </ul></div>
 </div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: July 28, 2022 at 11:11:09 GMT</small></p></td>
+<td align="left"><p><small>Last revised: November 17, 2022 at 14:54:40 GMT</small></p></td>
 <td align="right"><div class="copyright-footer"></div></td>
 </tr></table>
 <hr>

include/boost/geometry/geometries/concepts/box_concept.hpp

@@ -30,21 +30,6 @@
 namespace boost { namespace geometry { namespace concepts
 {
 
-
-/*!
-\brief Box concept
-\ingroup concepts
-\par Formal definition:
-The box concept is defined as following:
-- there must be a specialization of traits::tag defining box_tag as type
-- there must be a specialization of traits::point_type to define the
-  underlying point type (even if it does not consist of points, it should define
-  this type, to indicate the points it can work with)
-- there must be a specialization of traits::indexed_access, per index
-  (min_corner, max_corner) and per dimension, with two functions:
-  - get to get a coordinate value
-  - set to set a coordinate value (this one is not checked for ConstBox)
-*/
 template <typename Geometry>
 class Box
 {

include/boost/geometry/geometries/concepts/linestring_concept.hpp

@@ -35,45 +35,6 @@
 namespace boost { namespace geometry { namespace concepts
 {
 
-
-/*!
-\brief Linestring concept
-\ingroup concepts
-\par Formal definition:
-The linestring concept is defined as following:
-- there must be a specialization of traits::tag defining linestring_tag as type
-- it must behave like a Boost.Range
-- it must implement a std::back_insert_iterator
-    - either by implementing push_back
-    - or by specializing std::back_insert_iterator
-
-\note to fulfill the concepts, no traits class has to be specialized to
-define the point type.
-
-\par Example:
-
-A custom linestring, defining the necessary specializations to fulfill to the concept.
-
-Suppose that the following linestring is defined:
-\dontinclude doxygen_5.cpp
-\skip custom_linestring1
-\until };
-
-It can then be adapted to the concept as following:
-\dontinclude doxygen_5.cpp
-\skip adapt custom_linestring1
-\until }}
-
-\note
-- There is also the registration macro BOOST_GEOMETRY_REGISTER_LINESTRING
-- For registration of std::vector<P> (and deque, and list) it is enough to
-include the header-file geometries/adapted/std_as_linestring.hpp. That registers
-a vector as a linestring (so it cannot be registered as a linear ring then,
-in the same source code).
-
-
-*/
-
 template <typename Geometry>
 class Linestring
 {

include/boost/geometry/geometries/concepts/multi_linestring_concept.hpp

@@ -31,18 +31,6 @@
 namespace boost { namespace geometry { namespace concepts
 {
 
-
-/*!
-\brief multi-linestring concept
-\ingroup concepts
-\par Formal definition:
-The multi linestring concept is defined as following:
-- there must be a specialization of traits::tag defining multi_linestring_tag as
-  type
-- it must behave like a Boost.Range
-- its range value must fulfil the Linestring concept
-
-*/
 template <typename Geometry>
 class MultiLinestring
 {

include/boost/geometry/geometries/concepts/multi_point_concept.hpp

@@ -33,17 +33,6 @@
 namespace boost { namespace geometry { namespace concepts
 {
 
-
-/*!
-\brief MultiPoint concept
-\ingroup concepts
-\par Formal definition:
-The multi point concept is defined as following:
-- there must be a specialization of traits::tag defining multi_point_tag as type
-- it must behave like a Boost.Range
-- its range value must fulfil the Point concept
-
-*/
 template <typename Geometry>
 class MultiPoint
 {

include/boost/geometry/geometries/concepts/multi_polygon_concept.hpp

@@ -31,18 +31,6 @@
 namespace boost { namespace geometry { namespace concepts
 {
 
-
-/*!
-\brief multi-polygon concept
-\ingroup concepts
-\par Formal definition:
-The multi polygon concept is defined as following:
-- there must be a specialization of traits::tag defining multi_polygon_tag
-  as type
-- it must behave like a Boost.Range
-- its range value must fulfil the Polygon concept
-
-*/
 template <typename Geometry>
 class MultiPolygon
 {

include/boost/geometry/geometries/concepts/point_concept.hpp

@@ -35,63 +35,6 @@
 namespace boost { namespace geometry { namespace concepts
 {
 
-/*!
-\brief Point concept.
-\ingroup concepts
-
-\par Formal definition:
-The point concept is defined as following:
-- there must be a specialization of traits::tag defining point_tag as type
-- there must be a specialization of traits::coordinate_type defining the type
-  of its coordinates
-- there must be a specialization of traits::coordinate_system defining its
-  coordinate system (cartesian, spherical, etc)
-- there must be a specialization of traits::dimension defining its number
-  of dimensions (2, 3, ...) (derive it conveniently
-  from std::integral_constant<std::size_t, X> for X-D)
-- there must be a specialization of traits::access, per dimension,
-  with two functions:
-  - \b get to get a coordinate value
-  - \b set to set a coordinate value (this one is not checked for ConstPoint)
-- for non-Cartesian coordinate systems, the coordinate system's units
-  must either be boost::geometry::degree or boost::geometry::radian
-
-
-\par Example:
-
-A legacy point, defining the necessary specializations to fulfil to the concept.
-
-Suppose that the following point is defined:
-\dontinclude doxygen_5.cpp
-\skip legacy_point1
-\until };
-
-It can then be adapted to the concept as following:
-\dontinclude doxygen_5.cpp
-\skip adapt legacy_point1
-\until }}
-
-Note that it is done like above to show the system. Users will normally use the registration macro.
-
-\par Example:
-
-A read-only legacy point, using a macro to fulfil to the ConstPoint concept.
-It cannot be modified by the library but can be used in all algorithms where
-points are not modified.
-
-The point looks like the following:
-
-\dontinclude doxygen_5.cpp
-\skip legacy_point2
-\until };
-
-It uses the macro as following:
-\dontinclude doxygen_5.cpp
-\skip adapt legacy_point2
-\until end adaptation
-
-*/
-
 template <typename Geometry>
 class Point
 {

include/boost/geometry/geometries/concepts/ring_concept.hpp

@@ -34,22 +34,6 @@
 namespace boost { namespace geometry { namespace concepts
 {
 
-
-/*!
-\brief ring concept
-\ingroup concepts
-\par Formal definition:
-The ring concept is defined as following:
-- there must be a specialization of traits::tag defining ring_tag as type
-- it must behave like a Boost.Range
-- there can optionally be a specialization of traits::point_order defining the
-  order or orientation of its points, clockwise or counterclockwise.
-- it must implement a std::back_insert_iterator
-  (This is the same as the for the concept Linestring, and described there)
-
-\note to fulfill the concepts, no traits class has to be specialized to
-define the point type.
-*/
 template <typename Geometry>
 class Ring
 {

include/boost/geometry/geometries/concepts/segment_concept.hpp

@@ -32,25 +32,6 @@
 namespace boost { namespace geometry { namespace concepts
 {
 
-
-/*!
-\brief Segment concept.
-\ingroup concepts
-\details Formal definition:
-The segment concept is defined as following:
-- there must be a specialization of traits::tag defining segment_tag as type
-- there must be a specialization of traits::point_type to define the
-  underlying point type (even if it does not consist of points, it should define
-  this type, to indicate the points it can work with)
-- there must be a specialization of traits::indexed_access, per index
-  and per dimension, with two functions:
-  - get to get a coordinate value
-  - set to set a coordinate value (this one is not checked for ConstSegment)
-
-\note The segment concept is similar to the box concept, defining another tag.
-However, the box concept assumes the index as min_corner, max_corner, while
-for the segment concept there is no assumption.
-*/
 template <typename Geometry>
 class Segment
 {