Doc improvements (Feature Round #1 Reviews)

Triangulation_on_sphere_2/demo/Triangulation_on_sphere_2/simpleViewer.h

@@ -124,7 +124,7 @@ void Viewer::build_the_boundary(const Triangulation_on_sphere& T)
   for (typename Triangulation_on_sphere::All_edges_iterator 
     it=T.all_edges_begin();it!=T.all_edges_end();++it)
   {
-    if ( it->first->is_ghost() && 
+    if ( it->first->is_ghost() &&
          it->first->neighbor(it->second)->is_ghost() )
       continue;
 

Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/CGAL/Delaunay_triangulation_on_sphere_2.h

@@ -10,12 +10,12 @@ A Delaunay triangulation of a set of points is a triangulation of the sets of po
 the following <I>empty circle property</I> (also called <I>Delaunay property</I>): the circumscribing
 sphere of any simplex of the triangulation contains no point of the set in its interior.
 For a point set with no case of co-circularity of more than three points,
-the Delaunay triangulation is unique, it is the dual of the Voronoi diagram of the points.
+the Delaunay triangulation is unique, and defined as the dual of the Voronoi diagram of the points.
 
 The setting of 3D points on the 2-sphere is particular in that the empty circle property
 can be reduced to a single 3D orientation test \cgalCite{cgal:ccplr-redtp-10}.
 
-\tparam Traits is the geometric traits, which must be a model of `DelaunayTriangulationTraits_2`.
+\tparam Traits is the geometric traits; it must be a model of `DelaunayTriangulationTraits_2`.
 
 \tparam TDS is the triangulation data structure, which must be a model of `TriangulationDataStructure_2`.
         \cgal provides a default instantiation for this parameter, which is the class
@@ -33,12 +33,12 @@ class Delaunay_triangulation_on_sphere_2
   /// @{
 
   /*!
-  Introduces an empty triangulation.
+  introduces an empty triangulation.
   */
   Delaunay_triangulation_on_sphere_2(const Traits& gt = Traits());
 
   /*!
-  Introduces an empty triangulation and sets the center and radius of the sphere to `c` and `r` respectively.
+  introduces an empty triangulation and sets the center and radius of the sphere to `c` and `r` respectively.
   */
   Delaunay_triangulation_on_sphere_2(const Point_3& c, const FT r);
 
@@ -62,7 +62,7 @@ class Delaunay_triangulation_on_sphere_2
   /// @{
 
   /*!
-  Returns the side of `p` with respect to the circle circumscribing the triangle associated with `f`.
+  returns the side of `p` with respect to the circle circumscribing the triangle associated with `f`.
   */
   Oriented_side side_of_oriented_circle(Face_handle f, const Point& p) const;
 
@@ -79,15 +79,15 @@ class Delaunay_triangulation_on_sphere_2
   /// @{
 
   /*!
-  Inserts the point `p`.
+  inserts the point `p`.
   If the point `p` coincides with an already existing vertex, this vertex is returned
   and the triangulation remains unchanged.
   The optional parameter `f` is used to give a hint about the location of `p`.
   */
   Vertex_handle insert(const Point& p, Face_handle f = Face_handle());
 
   /*!
-  Inserts the point `p` at the location given by `(lt, loc, li)`.
+  inserts the point `p` at the location given by `(lt, loc, li)`.
   \sa `Triangulation_on_sphere_2::locate()`
   */
   Vertex_handle insert(const Point& p, Locate_type& lt, Face_handle loc, int li );
@@ -98,14 +98,14 @@ class Delaunay_triangulation_on_sphere_2
   Vertex_handle push_back(const Point& p);
 
   /*!
-  Inserts the points in the range `[first, last)` and returns the number of inserted points.
+  inserts the points in the range `[first, last)` and returns the number of inserted points.
   \tparam PointInputIterator must be an input iterator with the value type `Point`.
   */
   template <class PointInputIterator>
   std::ptrdiff_t insert(PointInputIterator first, PointInputIterator last);
 
   /*!
-  Removes the vertex `v` from the triangulation.
+  removes the vertex `v` from the triangulation.
   */
   void remove(Vertex_handle v);
 
@@ -115,10 +115,10 @@ class Delaunay_triangulation_on_sphere_2
   /// @{
 
   /*!
-  Outputs the faces and boundary edges of the conflict zone of point `p` into output iterators.
+  outputs the faces and boundary edges of the conflict zone of point `p` into output iterators.
 
   This function outputs in the container pointed to by `fit` the faces which are in conflict with point `p`,
-  i. e., the faces whose circumcircle contains `p`. It outputs in the container pointed to by `eit` the
+  i. e., the faces whose circumcircle contains `p`. It outputs in the container pointed to by `eit`
   the boundary of the zone in conflict with `p`. The boundary edges of the conflict zone
   are output in counter-clockwise order and each edge is described through its incident face
   which is not in conflict with `p`. The function returns in a `std::pair` the resulting output iterators.
@@ -148,44 +148,44 @@ class Delaunay_triangulation_on_sphere_2
   // Straight
 
   /*!
-  Returns the center of the circle circumscribed to face `f`
+  returns the center of the circle circumscribed to face `f`
   */
   Point_3 dual(const Face_handle f) const;
 
   /*!
-  Returns the line segment with endpoints the circumcenters of the faces incident to the edge `e`.
+  returns the line segment with endpoints the circumcenters of the faces incident to the edge `e`.
   */
   Segment_3 dual(const Edge& e) const;
 
   /*!
-  Same as above.
+  returns the line segment with endpoints the circumcenters of the faces incident to the edge `*ec`.
   */
   Segment_3 dual(const Edge_circulator ec) const;
 
   /*!
-  Same as above.
+  returns the line segment with endpoints the circumcenters of the faces incident to the edge `*ei`.
   */
   Segment_3 dual(const All_edges_iterator ei) const;
 
   // Curved
 
   /*!
-  Returns the intersection of the dual of the face `f` and the sphere
+  returns the intersection of the dual of the face `f` and the sphere
   */
   Point dual_on_sphere(const Face_handle f) const;
 
   /*!
-  Returns the arc of great circle with endpoints the circumcenters of the faces incident to the edge `e`.
+  returns the arc of great circle with endpoints the circumcenters of the faces incident to the edge `e`.
   */
   Arc_segment arc_dual(const Edge& e) const;
 
   /*!
-  Same as above.
+  returns the arc of great circle with endpoints the circumcenters of the faces incident to the edge `*ec`.
   */
   Arc_segment arc_dual(const Edge_circulator ec) const;
 
   /*!
-  Same as above.
+  returns the arc of great circle with endpoints the circumcenters of the faces incident to the edge `*ei`.
   */
   Arc_segment arc_dual(const All_edges_iterator ei) const;
 

Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/CGAL/Delaunay_triangulation_sphere_traits_2.h

@@ -3,57 +3,58 @@ namespace CGAL {
 /*!
 \ingroup PkgTriangulationOnSphere2TriangulationClasses
 
-\cgalModels `DelaunayTriangulationOnSphereTraits_2`
-
 The class `Delaunay_triangulation_sphere_traits_2` is a model
-of the concept `DelaunayTriangulationOnSphereTraits_2`. It implements the `Point_on_sphere_2` type
-as a kernel's `Point_3` type.
+of the concept `DelaunayTriangulationOnSphereTraits_2`.
+
+The `Point_on_sphere_2` type is implemented as a kernel's `Point_3` type.
 
 If the kernel template parameter `K` does not enable exact representation of points on sphere
 (i.e. at least a mean to represent algebraic coordinates), then it cannot be guaranteed
 that all points on the sphere are in a convex position and thus some points might be hidden upon insertion.
 It is possible to ensure that no point can be hidden by enforcing a tiny gap between points \cgalCite{cgal:ccplr-redtp-10}.
 In Lemma 4.1 of this publication, it is in particular proven that if points lie within a distance
-\f$ \delta \f$ of the sphere, then as long as points are separated by at least \f$ 2 \sqrt{R\delta} \f$
-with \f$ R \f$ the radius of the sphere, then no point is hidden.
+\f$ \delta \f$ of the sphere, no point is hidden as long as points are separated by at least \f$ 2 \sqrt{R\delta} \f$
+with \f$ R \f$ the radius of the sphere.
 
 Thus, if `K` offers exact representation, then \f$ \delta \f$ is set to \f$ 0 \f$.
-Otherwise, \f$ \delta \f$ is set to the maximal distance between two consecutive `K::FT`
+Otherwise, \f$ \delta \f$ is set to the maximal distance between two consecutive `LK::FT`
 for the coordinates of a point that is (theoretically) on the sphere.
 This bound \f$ \delta \f$ is then used in the functions `is_on_sphere()` and `are_points_too_close()`
 using the relation above to ensure that a point being inserted is either marked as "too close"
 (see \link CGAL::Triangulation_on_sphere_2::Locate_type `CGAL::Triangulation_on_sphere_2<Traits,TDS>::Locate_type` \endlink)
-and not inserted or guaranteed to not be hidden upon insertion.
+and thus not inserted, or guaranteed to not be hidden upon insertion.
 
-\tparam K a kernel type; must be a model of `Kernel`
-\tparam SK a spherical kernel type; must be a model of `SphericalKernel`
+\tparam K a linear kernel type; it must be a model of `Kernel`.
+\tparam SK a spherical kernel type; it must be a model of `SphericalKernel`.
+
+\cgalModels `DelaunayTriangulationOnSphereTraits_2`
 
 \sa `CGAL::Geographical_coordinates_traits_2`
 \sa `CGAL::Projection_sphere_traits_3`
 */
-template <typename K,
+template <typename LK,
           typename SK = CGAL::Spherical_kernel_3<
-                          K, CGAL::Algebraic_kernel_for_spheres_2_3<typename K::FT> > >
+                          K, CGAL::Algebraic_kernel_for_spheres_2_3<typename LK::FT> > >
 class Delaunay_triangulation_sphere_traits_2
 {
 public:
   /// The field number type
-  typedef typename K::FT                            FT;
+  typedef typename LK::FT                           FT;
 
   ///
-  typedef typename K::Point_3                       Point_on_sphere_2;
+  typedef typename LK::Point_3                      Point_on_sphere_2;
 
   /// An arc of a great circle, used to represent a curved segment on the sphere (Voronoi or Delaunay edge).
   typedef typename SK::Circular_arc_3               Arc_on_sphere_2;
 
   ///
-  typedef typename K::Point_3                       Point_3;
+  typedef typename LK::Point_3                      Point_3;
 
   ///
-  typedef typename K::Segment_3                     Segment_3;
+  typedef typename LK::Segment_3                    Segment_3;
 
   ///
-  typedef typename K::Triangle_3                    Triangle_3;
+  typedef typename LK::Triangle_3                   Triangle_3;
 
   /// \name Predicates
   ///
@@ -68,11 +69,11 @@ class Delaunay_triangulation_sphere_traits_2
   /// are aligned (and on the same side) with the center of the sphere.
   typedef unspecified_type                          Equal_on_sphere_2;
 
-  /// Internally uses a `K::Coplanar_orientation_3`
+  /// Internally uses a `LK::Coplanar_orientation_3`
   typedef unspecified_type                          Collinear_are_strictly_ordered_on_great_circle_2;
 
   ///
-  typedef typename K::Orientation_3                 Side_of_oriented_circle_2;
+  typedef typename LK::Orientation_3                 Side_of_oriented_circle_2;
 
   /// Internally uses `Orientation_3`
   typedef unspecified_type                          Orientation_on_sphere_2;
@@ -84,19 +85,19 @@ class Delaunay_triangulation_sphere_traits_2
   /// @{
 
   /// Internally uses `SK::Construct_circular_arc_3`
-  typedef typename unspecified_type                 Construct_arc_on_sphere_2;
+  typedef typename unspecified_type                Construct_arc_on_sphere_2;
 
   ///
   typedef typename unspecified_type                 Construct_circumcenter_on_sphere_2;
 
   ///
-  typedef typename K::Construct_point_3             Construct_point_3;
+  typedef typename LK::Construct_point_3            Construct_point_3;
 
   ///
-  typedef typename K::Construct_segment_3           Construct_segment_3;
+  typedef typename LK::Construct_segment_3          Construct_segment_3;
 
   ///
-  typedef typename K::Construct_triangle_3          Construct_triangle_3;
+  typedef typename LK::Construct_triangle_3         Construct_triangle_3;
 
   /// @}
 
@@ -105,11 +106,11 @@ class Delaunay_triangulation_sphere_traits_2
   ///
   /// @{
 
-  /// Returns whether `p` is exactly on the sphere if `K` can represent algebraic coordinates,
+  /// returns whether `p` is exactly on the sphere if `K` can represent algebraic coordinates,
   /// or whether `p` is within an automatically computed small distance otherwise.
   bool is_on_sphere(const Point_on_sphere_2& p) const;
 
-  /// Returns `false` if `K` can represent algebraic coordinates, or whether the distance
+  /// returns `false` if `K` can represent algebraic coordinates, or whether the distance
   /// between `p` and `q` is lower than \f$ 2 \sqrt{R\delta} \f$ otherwise.
   bool are_points_too_close(const Point_on_sphere_2& p, const Point_on_sphere_2& q) const;
 

Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/CGAL/Geographical_coordinates_traits_2.h

@@ -3,26 +3,26 @@ namespace CGAL {
 /*!
 \ingroup PkgTriangulationOnSphere2TriangulationClasses
 
-\cgalModels `DelaunayTriangulationOnSphereTraits_2`
-
 The class `Geographical_coordinates_traits_2` is a model
 of the concept `DelaunayTriangulationOnSphereTraits_2`. It implements the `Point_on_sphere_2` type
 as a pair of coordinates representing the latitude and the longitude of the point on the sphere.
 
-\tparam K a kernel type; must be a model of `Kernel`
+\tparam K a linear kernel type; must be a model of `Kernel`
 \tparam SK a spherical kernel type; must be a model of `SphericalKernel`
 
+\cgalModels `DelaunayTriangulationOnSphereTraits_2`
+
 \sa `CGAL::Delaunay_triangulation_sphere_traits_2`
 \sa `CGAL::Projection_sphere_traits_3`
 */
-template <typename K,
+template <typename LK,
           typename SK = CGAL::Spherical_kernel_3<
-                          K, CGAL::Algebraic_kernel_for_spheres_2_3<typename K::FT> > >
+                          K, CGAL::Algebraic_kernel_for_spheres_2_3<typename LK::FT> > >
 class Geographical_coordinates_traits_2
 {
 public:
   /// The field number type.
-  typedef typename K::FT                            FT;
+  typedef typename LK::FT                           FT;
 
   /// A pair of latitude and longitude values.
   typedef Geographical_coordinates<K>               Point_on_sphere_2;
@@ -31,13 +31,13 @@ class Geographical_coordinates_traits_2
   typedef typename SK::Circular_arc_3               Arc_on_sphere_2;
 
   ///
-  typedef typename K::Point_3                       Point_3;
+  typedef typename LK::Point_3                      Point_3;
 
   ///
-  typedef typename K::Segment_3                     Segment_3;
+  typedef typename LK::Segment_3                    Segment_3;
 
   ///
-  typedef typename K::Triangle_3                    Triangle_3;
+  typedef typename LK::Triangle_3                   Triangle_3;
 
   /// \name Predicates
   ///
@@ -70,7 +70,7 @@ class Geographical_coordinates_traits_2
   ///
   typedef typename unspecified_type                 Construct_circumcenter_on_sphere_2;
 
-  /// Converts points from the latitude/longitude system to the 3D Euclidean system
+  /// converts points from the latitude/longitude system to the 3D Euclidean system
   typedef unspecified_type                          Construct_point_3;
 
   ///
@@ -102,17 +102,17 @@ class Geographical_coordinates_traits_2
 \ingroup PkgTriangulationOnSphere2TriangulationClasses
 
 This class represents coordinates of the Geographical Coordinates System,
-that is a pair of two values representing a latitude and a longitude.
+that is a pair of scalar values representing a latitude and a longitude.
 
-\tparam K a kernel type; must be a model of `Kernel`
+\tparam K a kernel type; it must be a model of `Kernel`.
 
 */
 template< typename K >
 class Geographical_coordinates
 {
 public:
   /// The field number type
-  typedef typename K::FT                            FT;
+  typedef typename LK::FT                           FT;
 
   ///
   typedef FT                                        Latitude;
@@ -123,7 +123,7 @@ class Geographical_coordinates
   /// %Default constructor. Creates a point at coordinates `(0, 0)`.
   Geographical_coordinates();
 
-  /// Construct a point on the sphere at coordinates `(la, lo)`.
+  /// constructs a point on the sphere at coordinates `(la, lo)`.
   ///
   /// \pre `la` is within `[-90; 90[` and `lo` is within `[-180; 180[`.
   Geographical_coordinates(const Latitude la, const Longitude lo);