Adapt documentation according to the review

Author: LeoValque

Convex_hull_3/doc/Convex_hull_3/Convex_hull_3.txt

@@ -156,13 +156,12 @@ that is model of the concept `MutableFaceGraph`, e.g. `Polyhedron_3` and `Surfac
 
 \section Convex_hull_3Do_intersect Intersection test of Convex Hulls
 
-The `Convex_hull_3::do_intersect()` functions provide an implementation of the algorithm computing the intersection of two convex hulls by searching on the 2-sphere
-@todo Add \cgalCite{hornus2017convexintersection}.
+The `CGAL::Convex_hull_3::do_intersect()` functions provide an implementation of the algorithm computing the intersection of two convex hulls by searching on the 2-sphere \cgalCite{hornus2017convexintersection}.
 Input convex hulls can be provided in three forms: as range of points, as graph model of `AdjacencyGraph` or as instance of the `Convex_hull_hierarchy` class.
 
-The algorithm accesses the convex hulls using the `extreme_point_3()` function, which returns the point on the hull that is furthest in a specified direction.
-The `Convex_hull_hierarchy` class is a data structure that represents a convex hull and is optimized for efficient `extreme_point_3()` queries,
-which in turn makes `do_intersect()` particularly fast when using this representation.
+The algorithm accesses the convex hulls using the `CGAL::extreme_point_3()` function, which returns the point on the hull that is furthest in a specified direction.
+The `Convex_hull_hierarchy` class is a data structure that represents a convex hull and is optimized for efficient `CGAL::extreme_point_3()` queries,
+which in turn makes `CGAL::Convex_hull_3::do_intersect()` particularly fast when using this representation.
 
 The computational complexities of `extreme_point_3()` and consequently `do_intersect()` depend on the input type:  \f$O(n)\f$ for a range of point,
 \f$O(\sqrt{n})\f$ on average for a graph and \f$O(\log{n})\f$ on average for a Convex_hull_hierarchy.

Convex_hull_3/examples/Convex_hull_3/do_intersect_ch3.cpp

@@ -17,6 +17,7 @@ typedef CGAL::Exact_predicates_inexact_constructions_kernel      K;
 typedef K::Point_3                                               Point_3;
 typedef CGAL::Surface_mesh<Point_3>                              Mesh;
 typedef Mesh::Property_map<Mesh::Vertex_index, Point_3>          PointMap;
+typedef CGAL::Convex_hull_hierarchy<Mesh>                        Convex_hull_hierarchy;
 
 int main(int argc, char* argv[])
 {
@@ -52,12 +53,12 @@ int main(int argc, char* argv[])
                             << " extreme vertices in the input meshes.\n";
 
   // Convex_hull_hierarchy is data structure for very fast intersection test of Convex_hull
-  CGAL::Convex_hull_hierarchy<Mesh> hsm1(sm1);
-  CGAL::Convex_hull_hierarchy<Mesh> hsm2(sm2);
+  Convex_hull_hierarchy hsm1(sm1);
+  Convex_hull_hierarchy hsm2(sm2);
   res = CGAL::Convex_hull_3::do_intersect(hsm1, hsm2);
   std::cout << "do convex hulls intersect? " << std::boolalpha << res << "\n";
 
-  // Separation distance provides the squared distance between the two objects if they do not intersect but it's slower
+  // Separation distance provides the approximate squared distance between the two objects if they do not intersect but it's slower
   K::FT dist = CGAL::Convex_hull_3::separation_distance(hsm1, hsm2);
   std::cout << "Squared distance between convex hulls: " << dist << "\n";
 

Convex_hull_3/include/CGAL/Convex_hull_3/distance.h

@@ -347,8 +347,7 @@ struct Separation_distance_functor{
 /**
 * \ingroup PkgConvexHull3Predicates
 *
-* provides a lower bound on the squared distance between the convex hulls of the two point sets.
-* If the convex hulls do intersect, returns zero
+* computes a lower bound on the squared distance between the convex hulls of two point sets, returning zero when the hulls intersect.
 *
 * @tparam PointRange: is a model of `ConstRange`. The value type of its iterator is the key type of the named parameter `point_map`.
 * @tparam NamedParameters_1 a sequence of \ref bgl_namedparameters "Named Parameters"
@@ -381,6 +380,8 @@ struct Separation_distance_functor{
 *   \cgalParamNEnd
 * \cgalNamedParamsEnd
 *
+* \note The point sets do not need to be in convex position.
+*
 */
 template <class PointRange,
           class NamedParameters_1 = parameters::Default_named_parameters,
@@ -392,7 +393,7 @@ FT separation_distance(const PointRange& r1, const PointRange& r2,
 /**
 * \ingroup PkgConvexHull3Predicates
 *
-* provides a lower bound on the squared distance between the two convex graphs.
+* computes a lower bound on the squared distance between the two convex graphs, returning zero when their hulls intersect.
 *
 * @tparam AdjacencyGraph is a model of `AdjacencyGraph`.
 * @tparam NamedParameters_1 a sequence of \ref bgl_namedparameters "Named Parameters"
@@ -428,6 +429,8 @@ FT separation_distance(const PointRange& r1, const PointRange& r2,
 *   \cgalParamNEnd
 * \cgalNamedParamsEnd
 *
+* \see `CGAL::Convex_hull_3::do_intersect`
+*
 */
 template <class AdjacencyGraph,
           class NamedParameters_1 = parameters::Default_named_parameters,
@@ -439,9 +442,9 @@ FT separation_distance(const AdjacencyGraph& g1, const AdjacencyGraph& g2,
 /**
 * \ingroup PkgConvexHull3Predicates
 *
-* provides a lower bound on the squared distance between the two convex hulls.
+* computes a lower bound on the squared distance between the two convex hulls, returning zero when they intersect.
 *
-* @tparam PolygonMesh: is a model of `FaceGraph`, more details in `CGAL::Convex_hull_hierarchy`
+* @tparam ConvexHullHierarchy an instance of `CGAL::Convex_hull_hierarchy`
 * @tparam NamedParameters_1 a sequence of \ref bgl_namedparameters "Named Parameters"
 * @tparam NamedParameters_2 a sequence of \ref bgl_namedparameters "Named Parameters"
 *
@@ -473,11 +476,13 @@ FT separation_distance(const AdjacencyGraph& g1, const AdjacencyGraph& g2,
 *   \cgalParamNEnd
 * \cgalNamedParamsEnd
 *
+* \see `CGAL::Convex_hull_3::do_intersect`
+*
 */
-template <class PolygonMesh,
+template <class ConvexHullHierarchy,
           class NamedParameters_1 = parameters::Default_named_parameters,
           class NamedParameters_2 = parameters::Default_named_parameters>
-FT separation_distance(const Convex_hull_hierarchy<PolygonMesh>& ch1, const Convex_hull_hierarchy<PolygonMesh>& ch2,
+FT separation_distance(const ConvexHullHierarchy& ch1, const ConvexHullHierarchy& ch2,
                        const NamedParameters_1& np1 = parameters::default_values(),
                        const NamedParameters_2& np2 = parameters::default_values());
 

Convex_hull_3/include/CGAL/Convex_hull_3/intersections.h

@@ -274,7 +274,7 @@ Point_3 extreme_point_3(const PointRange& r, const Direction_3 &dir, const Named
 *
 * computes the furthest point of the convex hull along the direction.
 *
-* @tparam PolygonMesh: is a model of `MutableFaceGraph` For more details see in  `CGAL::Convex_hull_hierarchy`
+* @tparam ConvexHullHierarchy an instance of `CGAL::Convex_hull_hierarchy`
 * @tparam Direction_3: is a model of CGAL::Direction_3.
 * @tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
 *
@@ -302,8 +302,8 @@ Point_3 extreme_point_3(const PointRange& r, const Direction_3 &dir, const Named
 * \cgalNamedParamsEnd
 *
 */
-template <class PolygonMesh, class Direction_3, class NamedParameters>
-Point_3 extreme_point_3(const Convex_hull_hierarchy<PolygonMesh> &ch, const Direction_3 &dir, const NamedParameters &np);
+template <class ConvexHullHierarchy, class Direction_3, class NamedParameters>
+Point_3 extreme_point_3(const ConvexHullHierarchy &ch, const Direction_3 &dir, const NamedParameters &np);
 
 #else
 
@@ -552,7 +552,7 @@ struct Do_intersect_traits<K, K, Converter, true> {
 /**
 * \ingroup PkgConvexHull3Predicates
 *
-* checks if the convex hulls of the two point sets intersect or not. The points in a set do not need to be in convex position.
+* checks if the convex hulls of the two point sets intersect or not.
 *
 * @tparam PointRange: is a model of `ConstRange`. The value type of its iterator is the key type of the named parameter `point_map`.
 * @tparam NamedParameters_1 a sequence of \ref bgl_namedparameters "Named Parameters"
@@ -585,6 +585,8 @@ struct Do_intersect_traits<K, K, Converter, true> {
 *   \cgalParamNEnd
 * \cgalNamedParamsEnd
 *
+* * \note The point sets do not need to be in convex position.
+*
 */
 template <class PointRange,
           class NamedParameters_1 = parameters::Default_named_parameters,
@@ -645,7 +647,7 @@ bool do_intersect(const AdjacencyGraph& g1, const AdjacencyGraph& g2,
 *
 * checks if the convex hulls intersect or not.
 *
-* @tparam PolygonMesh: is a model of `MutableFaceGraph`, more details in `CGAL::Convex_hull_hierarchy`
+* @tparam ConvexHullHierarchy an instance of `CGAL::Convex_hull_hierarchy`
 * @tparam NamedParameters_1 a sequence of \ref bgl_namedparameters "Named Parameters"
 * @tparam NamedParameters_2 a sequence of \ref bgl_namedparameters "Named Parameters"
 *
@@ -678,10 +680,10 @@ bool do_intersect(const AdjacencyGraph& g1, const AdjacencyGraph& g2,
 * \cgalNamedParamsEnd
 *
 */
-template <class PolygonMesh,
+template <class ConvexHullHierarchy,
           class NamedParameters_1 = parameters::Default_named_parameters,
           class NamedParameters_2 = parameters::Default_named_parameters>
-bool do_intersect(const Convex_hull_hierarchy<PolygonMesh>& ch1, const Convex_hull_hierarchy<PolygonMesh>& ch2,
+bool do_intersect(const ConvexHullHierarchy& ch1, const ConvexHullHierarchy& ch2,
                   const NamedParameters_1& np1 = parameters::default_values(),
                   const NamedParameters_2& np2 = parameters::default_values());
 

Convex_hull_3/include/CGAL/Convex_hull_hierarchy.h

@@ -86,11 +86,9 @@ struct Convex_hull_hierarchy{
   *
   * @tparam VertexListGraph: a model of `VertexListGraph`
   * @tparam NamedParameters: a sequence of named parameters
-  * @tparam Traits: model of the concept ConvexHullTraits_3. For the purposes of checking the postcondition that the convex hull is valid, Traits must also be a model of the concept IsStronglyConvexTraits_3.
   *
   * @param g the graph
   * @param np an optional sequence of `Named Parameters` among the ones listed below
-  * @param traits an instance of Traits
   *
   * \cgalNamedParamsBegin
   *   \cgalParamNBegin{vertex_point_map}
@@ -163,13 +161,16 @@ struct Convex_hull_hierarchy{
   * construct the furthest point of the convex hull along the direction.
   *
   * @tparam `Direction_3` model of `Kernel::Direction_3`. The kernel does not require to be the same than the one using by the Mesh
+  * @tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
   *
   * @param dir the direction
+  * @param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below
   *
   * \return Return a `Point_3` using the same kernel as the direction.
   */
-  template <class Direction_3, typename NamedParameters=parameters::Default_named_parameters>
-  typename Kernel_traits<Direction_3>::Kernel::Point_3 extreme_point_3(const Direction_3 &dir, const NamedParameters & np=parameters::default_values) const {
+  template <typename Direction_3,
+            typename NamedParameters=parameters::Default_named_parameters>
+  typename Kernel_traits<Direction_3>::Kernel::Point_3 extreme_point_3(const Direction_3 &dir, const NamedParameters &np=parameters::default_values) const {
     using CGAL::parameters::choose_parameter;
     using CGAL::parameters::get_parameter;