Merge pull request #3015 from afabri/Polygon-improve_user_manual-GF

Polygon_2: Fix Section Headings

Polygon/doc/Polygon/PackageDescription.txt

@@ -38,6 +38,7 @@ The assertion flags for the polygons and polygon operations use
 ## Classes ##
 - `CGAL::Polygon_2<PolygonTraits_2, Container>`
 - `CGAL::Polygon_with_holes_2<PolygonTraits_2,Container>`
+- `CGAL::General_polygon_with_holes_2<General_polygon>`
 
 ## Global Functions ##
 - `CGAL::area_2()`

Polygon/doc/Polygon/Polygon.txt

@@ -8,7 +8,7 @@ namespace CGAL {
 \authors Geert-Jan Giezeman and Wieger Wesselink
 \cgalAutoToc
 
-\section Introduction
+\section secPolygonIntroduction Introduction
 
 A polygon is a closed chain of edges. Several algorithms are available for
 polygons. For some of those algorithms, it is necessary that the polygon is
@@ -32,14 +32,14 @@ Polygons are dynamic. Vertices can be modified, inserted and erased.
 They provide the algorithms described above as member functions.
 Moreover, they provide ways of iterating over the vertices and edges.
 
-Currently, the `Polygon_2` class is a nice wrapper around a container of
+The `Polygon_2` class is a wrapper around a container of
 points, but little more. Especially, computed values are not cached.
 That is, when the `Polygon_2::is_simple()` member function is called
 twice or more, the result is computed each time anew.
 
-\section Examples
+\section secPolygonExamples Examples
 
-\subsection The Polygon Class
+\subsection subsecPolygon The Polygon Class
 
 The following example creates a polygon and illustrates the usage of
 some member functions.
@@ -50,14 +50,14 @@ some member functions.
 A polygon and some points
 \cgalFigureEnd
 
-\subsection Algorithms Operating on Sequences of Points
+\subsection subsecPolygonAlgorithms Algorithms Operating on Sequences of Points
 
 The following example creates a polygon and illustrates the usage of
 some global functions that operate on sequences of points.
 
 \cgalExample{Polygon/polygon_algorithms.cpp}
 
-\subsection Polygons in 3D Space
+\subsection subsecPolygon3D Polygons in 3D Space
 
 Sometimes it is useful to run a 2D algorithm on 3D data.
 Polygons may be contours of a 3D object, where the contours
@@ -72,4 +72,14 @@ and 3D Linear Geometric %Kernel.
 
 */
 
+\section secPolygonWithHole Polygons with Holes
+
+This package also provides two classes to represent polygons with holes,
+namely `Polygon_with_holes_2` and `General_polygon_with_holes_2`. They
+can store a polygon that represents the outer boundary and a sequence
+of polygons that represent the holes.
+
+These classes do not add any semantic requirements on the simplicity
+or orientation of their boundary polygons.
+
 }

Polygon/include/CGAL/General_polygon_with_holes_2.h

@@ -42,6 +42,8 @@ the exposed type `General_polygon_2`. This type represents the
 outer boundary of the general polygon and the outer boundaries of
 each hole.
 
+\tparam Polygon_ must have input and output operators.
+
 \cgalModels `GeneralPolygonWithHoles_2`
 
 */
@@ -168,10 +170,9 @@ be free of comments. The default for writing is ASCII without
 comments.
 
 The number of curves of the outer boundary is exported followed by the
-curves themselves in counterclockwise order. Then, the number of holes
+curves themselves. Then, the number of holes
 is exported, and for each hole, the number of curves on its outer
-boundary is exported followed by the curves themselves in clockwise
-order.
+boundary is exported followed by the curves themselves.
 
 \relates General_polygon_with_holes_2
 */
@@ -218,10 +219,9 @@ An ASCII and a binary format exist. The stream detects the format
 automatically and can read both.
 
 The format consists of the number of curves of the outer boundary
-followed by the curves themselves in counterclockwise order, followed
+followed by the curves themselves, followed
 by the number of holes, and for each hole, the number of curves on its
-outer boundary is followed by the curves themselves in clockwise
-order.
+outer boundary is followed by the curves themselves.
 
 \relates General_polygon_with_holes_2
 */