doc clean up

AABB_tree/doc/AABB_tree/Concepts/AABBGeomTraits.h

@@ -132,62 +132,62 @@ typedef unspecified_type Equal_3;
 /// @{
 
 /*!
-Returns the intersection detection functor.
+returns the intersection detection functor.
 */
 Do_intersect_3 do_intersect_3_object();
 
 /*!
-Returns the intersection constructor.
+returns the intersection constructor.
 */
 Intersect_3 intersect_3_object();
 
 /*!
-Returns the sphere constructor.
+returns the sphere constructor.
 */
 Construct_sphere_3 construct_sphere_3_object();
 
 /*!
-Returns the closest point constructor.
+returns the closest point constructor.
 */
 Construct_projected_point_3 construct_projected_point_3_object();
 
 /*!
-Returns the compare distance constructor.
+returns the compare distance constructor.
 */
 Compare_distance_3 compare_distance_3_object();
 
 /*!
-Returns the closest point constructor.
+returns the closest point constructor.
 */
 Has_on_bounded_side_3 has_on_bounded_side_3_object();
 
 /*!
-Returns the squared radius functor.
+returns the squared radius functor.
 */
 Compute_squared_radius_3 compute_squared_radius_3_object();
 
 /*!
-Returns the squared distance functor.
+returns the squared distance functor.
 */
 Compute_squared_distance_3 compute_squared_distance_3_object();
 
 /*!
-Returns the `Less_x_3` functor.
+returns the `Less_x_3` functor.
 */
 Less_x_3 less_x_3_object();
 
 /*!
-Returns the `Less_y_3` functor.
+returns the `Less_y_3` functor.
 */
 Less_y_3 less_y_3_object();
 
 /*!
-Returns the `Less_z_3` functor.
+returns the `Less_z_3` functor.
 */
 Less_z_3 less_z_3_object();
 
 /*!
-Returns the equal functor.
+returns the equal functor.
 */
 Equal_3 equal_3_object();
 

AABB_tree/doc/AABB_tree/Concepts/AABBPrimitive.h

@@ -56,17 +56,17 @@ typedef unspecified_type Id;
 /// @{
 
 /*!
-Returns the datum (geometric object) represented by the primitive.
+returns the datum (geometric object) represented by the primitive.
 */
 Datum_reference datum();
 
 /*!
-Returns the corresponding identifier. This identifier is only used as a reference for the objects in the output of the `AABB_tree` methods.
+returns the corresponding identifier. This identifier is only used as a reference for the objects in the output of the `AABB_tree` methods.
 */
 Id id();
 
 /*!
-Returns a 3D point located on the geometric object represented by the primitive. This function is used to sort the primitives during the AABB tree construction as well as to construct the search KD-tree internal to the AABB tree used to accelerate distance queries.
+returns a 3D point located on the geometric object represented by the primitive. This function is used to sort the primitives during the AABB tree construction as well as to construct the search KD-tree internal to the AABB tree used to accelerate distance queries.
 */
 Point_reference reference_point();
 

AABB_tree/doc/AABB_tree/Concepts/AABBPrimitiveWithSharedData.h

@@ -66,22 +66,22 @@ typedef unspecified_type Shared_data;
 /// \name Operations
 /// @{
 /*!
-Returns the datum (geometric object) represented by the primitive.
+returns the datum (geometric object) represented by the primitive.
 */
 Datum_reference datum(const Shared_data& data);
 
 /*!
-Returns the corresponding identifier. This identifier is only used as a reference for the objects in the output of the `AABB_tree` methods.
+returns the corresponding identifier. This identifier is only used as a reference for the objects in the output of the `AABB_tree` methods.
 */
 Id id();
 
 /*!
-Returns a 3D point located on the geometric object represented by the primitive. This function is used to sort the primitives during the AABB tree construction as well as to construct the search KD-tree internal to the AABB tree used to accelerate distance queries.
+returns a 3D point located on the geometric object represented by the primitive. This function is used to sort the primitives during the AABB tree construction as well as to construct the search KD-tree internal to the AABB tree used to accelerate distance queries.
 */
 Point_reference reference_point(const Shared_data& data);
 
 /*!
-A static function responsible for the creation of the shared data of a primitive.
+constructs the shared data of a primitive.
 The parameter pack is such that there exists a constructor `template <class T1, class ... T> AABBPrimitiveWithSharedData (T1,T...)`.
 */
 template <class ... T>

AABB_tree/doc/AABB_tree/Concepts/AABBRayIntersectionTraits.h

@@ -44,7 +44,7 @@ public:
   typedef unspecified_type Intersection_distance;
 
   /*!
-    Returns the intersection distance functor.
+    returns the intersection distance functor.
   */
   Intersection_distance intersection_distance_object() const ;
 };

AABB_tree/doc/AABB_tree/Concepts/AABBTraits.h

@@ -164,42 +164,42 @@ typedef unspecified_type Equal_3;
 /// @{
 
 /*!
-Returns the primitive splitting functor.
+returns the primitive splitting functor.
 */
 Split_primitives split_primitives_object();
 
 /*!
-Returns the bounding box constructor.
+returns the bounding box constructor.
 */
 Compute_bbox compute_bbox_object();
 
 /*!
-Returns the intersection detection functor.
+returns the intersection detection functor.
 */
 Do_intersect do_intersect_object();
 
 /*!
-Returns the intersection constructor.
+returns the intersection constructor.
 */
 Intersection intersection_object();
 
 /*!
-Returns the distance comparison functor.
+returns the distance comparison functor.
 */
 Compare_distance compare_distance_object();
 
 /*!
-Returns the closest point constructor.
+returns the closest point constructor.
 */
 Closest_point closest_point_object();
 
 /*!
-Returns the squared distance functor.
+returns the squared distance functor.
 */
 Squared_distance squared_distance_object();
 
 /*!
-Returns the equal functor.
+returns the equal functor.
 */
 Equal_3 equal_3_object();
 
@@ -220,7 +220,7 @@ void set_shared_data(T ... t);
 {}
 
 /*!
-Returns the shared data of the primitive constructed after a call to `set_shared_data`.
+returns the shared data of the primitive constructed after a call to `set_shared_data`.
 If no call to `set_shared_data` has been done, `Primitive::Shared_data()` is returned.
 */
 const Primitive::Shared_data& shared_data() const;

AABB_tree/doc/AABB_tree/aabb_tree.txt

@@ -336,7 +336,7 @@ inside the bounding box.
 The experiments described above are neither exhaustive nor conclusive
 as we have chosen one specific case where the input primitives are the
 facets of a triangle surface polyhedron. Nevertheless we now provide
-some general observations and advices about how to put the AABB tree
+some general observations and advises about how to put the AABB tree
 to use with satisfactory performances. While the tree construction
 times and memory occupancy do not fluctuate much in our experiments
 depending on the input surface triangle mesh, the performance
@@ -435,7 +435,7 @@ Camille Wormser and Pierre Alliez started working on a data structure
 for efficient collision detection in 2007. The generic design for
 implementing both intersection and distance queries, and for generic
 queries and primitives was developed by Camille Wormser. In 2009,
-Pierre Alliez, Stéphane Tayeb and Camille Wormser made the
+Pierre Alliez, Stéphane Tayeb and Camille Wormser made the
 implementation CGAL-compliant, with the help of Laurent Rineau for
 optimizing the tree construction. The authors wish to thank Andreas
 Fabri, Jane Tournois, Mariette Yvinec and Sylvain Lefèbvre for

AABB_tree/include/CGAL/AABB_face_graph_triangle_primitive.h

@@ -130,7 +130,7 @@ public:
   // constructors
   /*!
     \tparam Iterator an input iterator with `Id` as value type.
-    Constructs a primitive.
+    constructs a primitive.
     If `VertexPointPMap` is the default of the class, an additional constructor
     is available with `vppm` set to `get(vertex_point, graph)`.
   */
@@ -142,7 +142,7 @@ public:
   {}
 
   /*!
-    Constructs a primitive.
+    constructs a primitive.
     If `VertexPointPMap` is the default of the class, an additional constructor
     is available with `vppm` set to `get(vertex_point, graph)`.
   */

AABB_tree/include/CGAL/AABB_halfedge_graph_segment_primitive.h

@@ -141,7 +141,7 @@ public:
   typedef typename boost::graph_traits<HalfedgeGraph>::edge_descriptor edge_descriptor;
 
   /*!
-  Constructs a primitive.
+  constructs a primitive.
   \tparam Iterator is an input iterator with `Id` as value type.
   This \ref AABB_tree/AABB_halfedge_graph_edge_example.cpp "example" gives a way to call this constructor
   using the insert-by-range method of the class `AABB_tree<Traits>`.
@@ -156,7 +156,7 @@ public:
   {}
 
   /*!
-  Constructs a primitive.
+  constructs a primitive.
   If `VertexPointPMap` is the default of the class, an additional constructor
   is available with `vppm` set to `boost::get(vertex_point, graph)`.
   */

AABB_tree/include/CGAL/AABB_primitive.h

@@ -112,14 +112,14 @@ struct AABB_primitive
   /// @}
 
   /*!
-  Constructs a primitive and initializes the property maps.
+  constructs a primitive and initializes the property maps.
   */
   AABB_primitive(Id id,
                  ObjectPropertyMap o_pmap=ObjectPropertyMap(),
                  PointPropertyMap p_pmap=PointPropertyMap());
 
   /*!
-  Constructs a primitive from an iterator with `Id` as value type
+  constructs a primitive from an iterator with `Id` as value type
   and initializes the property maps.
   */
   template <class Iterator>

AABB_tree/include/CGAL/AABB_segment_primitive.h

@@ -88,7 +88,7 @@ class AABB_segment_primitive
                           Tag_false,
                           CacheDatum > Base;
 public:
-  ///Constructor from an iterator
+  ///constructor from an iterator
   AABB_segment_primitive(Iterator it) : Base(it){}
 };
 

AABB_tree/include/CGAL/AABB_tree.h

@@ -39,7 +39,7 @@ namespace CGAL {
 /// @{
 
   /**
-   * Class AABB_tree is a static data structure for efficient
+   * Static data structure for efficient
    * intersection and distance computations in 3D. It builds a
    * hierarchy of axis-aligned bounding boxes (an AABB tree) from a set
    * of 3D geometric objects, and can receive intersection and distance
@@ -109,7 +109,7 @@ namespace CGAL {
     /// \name Creation
     ///@{
 
-    /// Constructs an empty tree, and initializes the internally stored traits
+    /// constructs an empty tree, and initializes the internally stored traits
     /// class using `traits`.
     AABB_tree(const AABBTraits& traits = AABBTraits());
 
@@ -118,22 +118,21 @@ namespace CGAL {
      * @param first iterator over first primitive to insert
      * @param beyond past-the-end iterator
      *
-     * It is equivalent to constructing an empty tree and calling `insert(first,last,t...)`.
+     * constructs an empty tree followed by a call to `insert(first,last,t...)`.
      * The tree stays empty if the memory allocation is not successful.
      */
     template<typename InputIterator,typename ... T>
     AABB_tree(InputIterator first, InputIterator beyond,T&& ...);
 
-    /// After one or more calls to `insert()` the internal data
+    /// triggers the (re)construction of the internal tree structure.
-    /// structure of the tree must be reconstructed. This procedure
+    /// The internal tree structure is automatically invalidated by the insertion of any primitives
-    /// has a complexity of \f$O(n log(n))\f$, where \f$n\f$ is the number of
+    /// after one or more calls to `insert()`.
-    /// primitives of the tree.  This procedure is called implicitly
+    /// This procedure is called implicitly at the first call to a query member function.
-    /// at the first call to a query member function. You can call
+    /// An explicit call to `build()` must be made to ensure that the next call to
-    /// `build()` explicitly to ensure that the next call to
+    /// a query function will not trigger the construction of the data structure.
-    /// query functions will not trigger the reconstruction of the
+    /// A call to `AABBTraits::set_shared_data(t...)` is made using the internally stored traits.
-    /// data structure.
+    /// This procedure has a complexity of \f$O(n log(n))\f$, where \f$n\f$ is the number of
-    /// A call to `AABBTraits::set_shared_data(t...)`
+    /// primitives of the tree.
-    /// is made using the internally stored traits.
     template<typename ... T>
     void build(T&& ...);
 #ifndef DOXYGEN_RUNNING
@@ -144,13 +143,13 @@ namespace CGAL {
     /// \name Operations
     ///@{
 
-    /// Equivalent to calling `clear()` and then `insert(first,last,t...)`.
+    /// is equivalent to calling `clear()`, `insert(first,last,t...)`, and `build()`
     template<typename ConstPrimitiveIterator,typename ... T>
     void rebuild(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond,T&& ...);
 
 
-    /// Add a sequence of primitives to the set of primitives of the AABB tree.
+    /// adds a sequence of primitives to the set of primitives of the AABB tree.
-    /// `%InputIterator` is any iterator and the parameter pack `T` are any types
+    /// `%InputIterator` is any iterator and the parameter pack `T` contains any types
     /// such that `Primitive` has a constructor with the following signature:
     /// `Primitive(%InputIterator, T...)`. If `Primitive` is a model of the concept
     /// `AABBPrimitiveWithSharedData`, a call to `AABBTraits::set_shared_data(t...)`
@@ -158,20 +157,20 @@ namespace CGAL {
     template<typename InputIterator,typename ... T>
     void insert(InputIterator first, InputIterator beyond,T&& ...);
 
-    /// Adds a primitive to the set of primitives of the tree.
+    /// adds a primitive to the set of primitives of the tree.
     inline void insert(const Primitive& p);
 
-    /// Clears and destroys the tree.
+    /// clears and destroys the tree.
     ~AABB_tree()
     {
       clear();
     }
-    /// Returns a const reference to the internally stored traits class.
+    /// returns a const reference to the internally stored traits class.
     const AABBTraits& traits() const{
       return m_traits;
     }
 
-    /// Clears the tree and the search tree if it was constructed,
+    /// clears the tree and the search tree if it was constructed,
     /// and switches on the usage of the search tree to find the hint for the distance queries
     void clear()
     {
@@ -182,7 +181,7 @@ namespace CGAL {
       m_use_default_search_tree = true;
     }
 
-    /// Returns the axis-aligned bounding box of the whole tree.
+    /// returns the axis-aligned bounding box of the whole tree.
     /// \pre `!empty()`
     const Bounding_box bbox() const {
       CGAL_precondition(!empty());
@@ -193,10 +192,10 @@ namespace CGAL {
                       m_primitives.end());
     }
 
-    /// Returns the number of primitives in the tree.
+    /// returns the number of primitives in the tree.
     size_type size() const { return m_primitives.size(); }
 
-    /// Returns \c true, iff the tree contains no primitive.
+    /// returns \c true, iff the tree contains no primitive.
     bool empty() const { return m_primitives.empty(); }
     ///@}
 
@@ -220,39 +219,38 @@ public:
     /// \name Intersection Tests
     ///@{
 
-    /// Returns `true`, iff the query intersects at least one of
+    /// returns `true`, iff the query intersects at least one of
-    /// the input primitives. \tparam Query must be a type for
+    /// the input primitives.
-    /// which `do_intersect` predicates are
+    /// \tparam Query must be a type for which `Do_intersect` operators are
-    /// defined in the traits class `AABBTraits`.
+    ///               defined in the traits class `AABBTraits`.
     template<typename Query>
     bool do_intersect(const Query& query) const;
 
-    /// Returns the number of primitives intersected by the
+    /// returns the number of primitives intersected by the
-    /// query. \tparam Query must be a type for which
+    /// query.
-    /// `do_intersect` predicates are defined
+    /// \tparam Query must be a type for which `Do_intersect` operators are
-    /// in the traits class `AABBTraits`.
+    ///               defined in the traits class `AABBTraits`.
     template<typename Query>
     size_type number_of_intersected_primitives(const Query& query) const;
 
-    /// Outputs to the iterator the list of all intersected primitives
+    /// puts in `out` the ids of all intersected primitives.
-    /// ids. This function does not compute the intersection points
+    /// This function does not compute the intersection points
     /// and is hence faster than the function `all_intersections()`
-    /// function below. \tparam Query must be a type for which
+    /// function below.
-    /// `do_intersect` predicates are defined
+    /// \tparam Query must be a type for which `Do_intersect` operators are
-    /// in the traits class `AABBTraits`.
+    ///               defined in the traits class `AABBTraits`.
     template<typename Query, typename OutputIterator>
     OutputIterator all_intersected_primitives(const Query& query, OutputIterator out) const;
 
 
-    /// Returns the intersected primitive id that is encountered first
+    /// returns the id of the intersected primitive that is encountered first
     /// in the tree traversal, iff
     /// the query intersects at least one of the input primitives. No
     /// particular order is guaranteed over the tree traversal, such
     /// that, e.g, the primitive returned is not necessarily the
-    /// closest from the source point of a ray query. \tparam Query
+    /// closest from the source point of a ray query.
-    /// must be a type for which
+    /// \tparam Query must be a type for which `Do_intersect` operators are
-    /// `do_intersect` predicates are defined
+    ///               defined in the traits class `AABBTraits`.
-    /// in the traits class `AABBTraits`.
     template <typename Query>
     boost::optional<Primitive_id> any_intersected_primitive(const Query& query) const;
     ///@}
@@ -260,30 +258,29 @@ public:
     /// \name Intersections
     ///@{
 
-    /// Outputs the list of all intersections, as objects of
+    /// puts in `out` all intersections, as objects of
     /// `Intersection_and_primitive_id<Query>::%Type`,
     /// between the query and the input data to
-    /// the iterator. `do_intersect()`
+    /// the iterator.
-    /// predicates and intersections must be defined for `Query`
+    /// \tparam Query must be a type for which `Do_intersect` and `Intersection` operators are
-    /// in the `AABBTraits` class.
+    ///               defined in the traits class `AABBTraits`.
     template<typename Query, typename OutputIterator>
     OutputIterator all_intersections(const Query& query, OutputIterator out) const;
 
 
-    /// Returns the intersection that is encountered first
+    /// returns if any the intersection that is encountered first
     /// in the tree traversal. No particular
     /// order is guaranteed over the tree traversal, e.g, the
-    /// primitive returned is not necessarily the closest from the
+    /// primitive returned is not necessarily the closest from the query.
-    /// source point of a ray query. Type `Query` must be a type
+    /// \tparam Query must be a type for which `Do_intersect` and `Intersection` operators are
-    /// for which `do_intersect` predicates
+    ///               defined in the traits class `AABBTraits`.
-    /// and intersections are defined in the traits class AABBTraits.
     template <typename Query>
     boost::optional< typename Intersection_and_primitive_id<Query>::Type >
     any_intersection(const Query& query) const;
 
 
 
-    /// Returns the intersection and  primitive id closest to the source point of the ray
+    /// returns the intersection and  primitive id closest to the source point of the ray
     /// query.
     /// \tparam Ray must be the same as `AABBTraits::Ray_3` and
     /// `do_intersect` predicates and intersections for it must be
@@ -314,7 +311,7 @@ public:
     }
     /// \endcond
 
-    /// Returns the primitive id closest to the source point of the ray
+    /// returns the primitive id closest to the source point of the ray
     /// query.
     /// \tparam Ray must be the same as `AABBTraits::Ray_3` and
     /// `do_intersect` predicates and intersections for it must be
@@ -343,12 +340,12 @@ public:
     /// \name Distance Queries
     ///@{
 
-    /// Returns the minimum squared distance between the query point
+    /// returns the minimum squared distance between the query point
     /// and all input primitives.
     /// \pre `!empty()`
     FT squared_distance(const Point& query) const;
 
-    /// Returns the point in the union of all input primitives which
+    /// returns the point in the union of all input primitives which
     /// is closest to the query. In case there are several closest
     /// points, one arbitrarily chosen closest point is
     /// returned.
@@ -356,7 +353,7 @@ public:
     Point closest_point(const Point& query) const;
 
 
-    /// Returns a `Point_and_primitive_id` which realizes the
+    /// returns a `Point_and_primitive_id` which realizes the
     /// smallest distance between the query point and all input
     /// primitives.
     /// \pre `!empty()`
@@ -422,14 +419,14 @@ public:
     /// the first distance query or by a call to `accelerate_distance_queries()`.
     ///@{
 
-    /// Constructs internal search tree from
+    /// constructs the internal search tree from
     /// a point set taken on the internal primitives
     /// returns `true` iff successful memory allocation
     bool accelerate_distance_queries();
-    /// Turns off the usage of the internal search tree and clears it if it was already constructed.
+    /// turns off the usage of the internal search tree and clears it if it was already constructed.
     void do_not_accelerate_distance_queries();
 
-    /// Constructs an internal KD-tree containing the specified point
+    /// constructs an internal KD-tree containing the specified point
     /// set, to be used as the set of potential hints for accelerating
     /// the distance queries. Note that the search tree built in
     /// this function will not be invalidated by the insertion of a new
@@ -444,19 +441,19 @@ public:
       return build_kd_tree(first,beyond);
     }
 
-    /// Returns the minimum squared distance between the query point
+    /// returns the minimum squared distance between the query point
     /// and all input primitives. The internal KD-tree is not used.
     /// \pre `!empty()`
     FT squared_distance(const Point& query, const Point& hint) const;
 
-    /// Returns the point in the union of all input primitives which
+    /// returns the point in the union of all input primitives which
     /// is closest to the query. In case there are several closest
     /// points, one arbitrarily chosen closest point is returned. The
     /// internal KD-tree is not used.
     /// \pre `!empty()`
     Point closest_point(const Point& query, const Point& hint) const;
 
-    /// Returns a `Point_and_primitive_id` which realizes the
+    /// returns a `Point_and_primitive_id` which realizes the
     /// smallest distance between the query point and all input
     /// primitives. The internal KD-tree is not used.
     /// \pre `!empty()`

AABB_tree/include/CGAL/AABB_triangle_primitive.h

@@ -88,7 +88,7 @@ class AABB_triangle_primitive
                           Tag_false,
                           CacheDatum > Base;
 public:
-  ///Constructor from an iterator
+  ///constructor from an iterator
   AABB_triangle_primitive(Iterator it) : Base(it){}
 };