From 74b8893cb09af0a40615846906172c3a57e61da0 Mon Sep 17 00:00:00 2001 From: Weisheng Si Date: Tue, 23 Jun 2015 08:39:35 +1000 Subject: [PATCH] Improve the comments --- .../Concepts/ConstructConeBasedSpanner_2.h | 11 +++- .../include/CGAL/Compute_cone_boundaries_2.h | 23 +++---- .../include/CGAL/Construct_theta_graph_2.h | 61 ++++++++----------- .../include/CGAL/Construct_yao_graph_2.h | 59 ++++++++---------- .../include/CGAL/gnuplot_output_2.h | 6 +- 5 files changed, 69 insertions(+), 91 deletions(-) diff --git a/Cone_spanners_2/doc/Cone_spanners_2/Concepts/ConstructConeBasedSpanner_2.h b/Cone_spanners_2/doc/Cone_spanners_2/Concepts/ConstructConeBasedSpanner_2.h index 1263ac5e902..95607a450e8 100644 --- a/Cone_spanners_2/doc/Cone_spanners_2/Concepts/ConstructConeBasedSpanner_2.h +++ b/Cone_spanners_2/doc/Cone_spanners_2/Concepts/ConstructConeBasedSpanner_2.h @@ -26,14 +26,14 @@ typedef Kernel_ kernel_type; /*! The graph type to store the constructed cone based spanner. It should be a model of both concepts MutableGraph and VertexAndEdgeListGraph in BGL. Of the two graph classes provided in BGL: `adjacency_list` and `adjacency_matrix`, only `adjacency_list` is such a model. - So pls use `adjacency_list` to be your graph type. Note that there are seven template parameters for + So please use `adjacency_list` to be your graph type. Note that there are seven template parameters for `boost::adjacency_list`: `OutEdgeList`, `VertexList`, `Directed`, `VertexProperties`, `EdgeProperties`, `GraphProperties`, `EdgeList`, of which we only require the `VertexProperties` be `CGAL::Point_2`, while other parameters can be chosen freely. Here `Point_2` is passed directly as bundled properties to `adjacency_list` because this makes our implementation much more straightforward than using property maps. - For detailed information about bundled properties, pls refer to + For detailed information about bundled properties, please refer to http://www.boost.org/doc/libs/1_58_0/libs/graph/doc/bundles.html. - If more properties for vertices are needed, you can add them later as external properties using + If more properties for vertices are needed, they can be added later as external properties using property maps. */ typedef Graph_ graph_type; @@ -62,6 +62,11 @@ Construct_spanner_2(unsigned int k, Direction_2 initial_direction = Direction_2( * * This operator implements the algorithm to build the spanner. * + * \tparam PointInputIterator This template parameter is to give the application developer freedom + * in choosing whichever Iterator he/she will use to input the coordinates of the points. + * If omitted, the type of the Iterator can be inferred from the arguments passed to the + * operator(). + * * \param start[in] An iterator pointing to the first point (vertex). * \param end[in] An iterator pointing to the place that passes the last point. * \param g[out] The constructed graph object. diff --git a/Cone_spanners_2/include/CGAL/Compute_cone_boundaries_2.h b/Cone_spanners_2/include/CGAL/Compute_cone_boundaries_2.h index 1a57839f98c..f25e71e8e5d 100644 --- a/Cone_spanners_2/include/CGAL/Compute_cone_boundaries_2.h +++ b/Cone_spanners_2/include/CGAL/Compute_cone_boundaries_2.h @@ -44,8 +44,7 @@ namespace CGAL { /*! \ingroup PkgConeBasedSpanners * * \brief The functor for computing the directions of cone boundaries with a given - * cone number and a given initial direction. The results are returned through the reference - * argument: vector \p rays. + * cone number and a given initial direction. * * This computation can be either inexact by simply dividing an approximate Pi by the cone number * (which is quick), or exact by using roots of polynomials (requiring number types such as `CORE::Expr` or `LEDA::Real`, @@ -64,6 +63,8 @@ namespace CGAL { * Of course, this functor can also be used in other applications where the plane needs to be divided * into equally-angled cones. * + * \cgalModels `ComputeConeBoundaries_2` + * */ template class Compute_cone_boundaries_2 { @@ -119,21 +120,15 @@ public: }; -/*! \ingroup PkgConeBasedSpanners - * - * \brief The specialised functor for computing the directions of cone boundaries exactly - * with a given cone number and a given initial direction. The results are returned by the reference - * argument: vector \p rays. - * - * \tparam Kernel_ If this parameter is `Exact_predicates_exact_constructions_kernel_with_sqrt`, - * this specialization functor will be called; otherwise, the general functor will - * be called. +/* + * The specialised functor for computing the directions of cone boundaries exactly + * with a given cone number and a given initial direction. */ template <> class Compute_cone_boundaries_2 { public: - /*! Indicate the type of the \cgal kernel. */ + /* Indicate the type of the cgal kernel. */ typedef Exact_predicates_exact_constructions_kernel_with_sqrt kernel_type; private: @@ -145,10 +140,10 @@ public: /* No member variables in this class, so a Constructor is not needed. */ // Compute_cone_boundaries_2() {}; - /*! \brief The operator(). + /* The operator(). * * The direction of the first ray can be specified by the parameter - * \p initial_direction, which allows the first ray to start at any direction. The remaining rays are calculated in + * initial_direction, which allows the first ray to start at any direction. The remaining rays are calculated in * counter-clockwise order. * * \param[in] cone_number The number of cones diff --git a/Cone_spanners_2/include/CGAL/Construct_theta_graph_2.h b/Cone_spanners_2/include/CGAL/Construct_theta_graph_2.h index c2b68d406e1..3bae1e02dd8 100644 --- a/Cone_spanners_2/include/CGAL/Construct_theta_graph_2.h +++ b/Cone_spanners_2/include/CGAL/Construct_theta_graph_2.h @@ -45,22 +45,13 @@ namespace CGAL { /*! \ingroup PkgConeBasedSpanners - \brief A functor for constructing theta graphs with a given set of 2D points. + \brief A template functor for constructing Theta graphs with a given set of 2D points and + a given initial direction for the cone boundaries. - \tparam Kernel_ The CGAL kernel used by this functor. If this parameter is - `CGAL::Exact_predicates_exact_constructions_kernel_with_sqrt`, - the graph will be constructed exactly; otherwise, inexactly using an approximate PI=3.1415... - - \tparam Graph_ The graph type to store the constructed Theta graph. It should be a model of - both concepts MutableGraph and VertexAndEdgeListGraph in BGL. Of the two graph classes provided - in BGL: `adjacency_list` and `adjacency_matrix`, only `adjacency_list` is such a model. - So pls use `adjacency_list` to be your graph type. Note that there are seven template parameters for - `boost::adjacency_list`: `OutEdgeList`, `VertexList`, `Directed`, `VertexProperties`, `EdgeProperties`, - `GraphProperties`, `EdgeList`, of which we require `VertexProperties` be `Point_2` from \cgal, - and other parameters can be chosen freely. Here `Point_2` is passed directly as bundled properties - to `adjacency_list` because this makes our implementation much more straightforward than using property maps. - For detailed information about bundled properties, pls refer to - http://www.boost.org/doc/libs/1_58_0/libs/graph/doc/bundles.html. + For the meaning and use of its template parameters, please refer to the concept + `ConstructConeBasedSpanner_2`. + + \cgalModels `ConstructConeBasedSpanner_2` */ template class Construct_theta_graph_2 { @@ -88,13 +79,12 @@ private: public: /*! \brief Constructor. - * - * Constructs a `Construct_theta_graph_2` object. - * - * \param k Number of cones to divide space into - * \param initial_direction A direction denoting one of the rays deviding the - * cones. This allows arbitary rotations of the rays that divide - * the plane. (default: positive x-axis) + Constructs a `Construct_theta_graph_2` object. + + \param k Number of cones to divide space into + \param initial_direction A direction denoting one of the rays deviding the + cones. This allows arbitary rotations of the rays that divide + the plane. (default: positive x-axis) */ Construct_theta_graph_2 (unsigned int k, Direction_2 initial_direction = Direction_2(1,0) ) @@ -114,21 +104,20 @@ public: } /*! \brief Copy constructor. - * \param x another Construct_theta_graph_2 object to copy from. + \param x another Construct_theta_graph_2 object to copy from. */ Construct_theta_graph_2 (const Construct_theta_graph_2& x) : cone_number(x.cone_number), rays(x.rays) {} /*! \brief Operator to construct a Theta graph. - * - * This operator implements the algorithm for adding edges to build the Theta graph. - * The algorithm implemented is described in: - * Giri Narasimhan and Michiel Smid, Chapter 4: Spanners based on the Theta graph, Geometric Spanner Networks, - * Cambridge University Press, 2007. - * This algorithm has the complexity of O(n*log(n)), which is optimal. - * - * \param start[in] An iterator pointing to the first point (vertex). - * \param end[in] An iterator pointing to the place that passes the last point. - * \param g[out] The constructed graph object. + This operator implements the algorithm for adding edges to build the Theta graph. + The algorithm implemented is described in: + Giri Narasimhan and Michiel Smid, Chapter 4: Spanners based on the Theta graph, Geometric Spanner Networks, + Cambridge University Press, 2007. + This algorithm has the complexity of O(n*log(n)), which is optimal. + + \param start[in] An iterator pointing to the first point (vertex). + \param end[in] An iterator pointing to the place that passes the last point. + \param g[out] The constructed graph object. */ template Graph_& operator()(const PointInputIterator& start, @@ -159,8 +148,8 @@ public: } /*! \brief returns the vector of the directions of the rays dividing the plane. - * - * \return a vector of Direction_2 + + \return a vector of Direction_2 */ const std::vector& directions() const { return rays; @@ -168,7 +157,7 @@ public: protected: - /* \brief Construct edges in one cone bounded by two directions. + /* Construct edges in one cone bounded by two directions. \param cwBound The direction of the clockwise boundary of the cone. \param ccwBound The direction of the counter-clockwise boundary. diff --git a/Cone_spanners_2/include/CGAL/Construct_yao_graph_2.h b/Cone_spanners_2/include/CGAL/Construct_yao_graph_2.h index 5aecf5ac4b9..f4eda45b7c5 100644 --- a/Cone_spanners_2/include/CGAL/Construct_yao_graph_2.h +++ b/Cone_spanners_2/include/CGAL/Construct_yao_graph_2.h @@ -43,22 +43,13 @@ namespace CGAL { /*! \ingroup PkgConeBasedSpanners - \brief A functor for constructing yao graphs with a given set of 2D points. + \brief A template functor for constructing Yao graphs with a given set of 2D points and + a given initial direction for the cone boundaries. - \tparam Kernel_ The CGAL kernel used by this functor. If this parameter is - `CGAL::Exact_predicates_exact_constructions_kernel_with_sqrt`, - the graph will be constructed exactly; otherwise, inexactly using an approximate PI=3.1415... + For the meaning and use of its template parameters, please refer to the concept + `ConstructConeBasedSpanner_2`. - \tparam Graph_ The graph type to store the constructed Yao graph. It should be a model of - both concepts MutableGraph and VertexAndEdgeListGraph in BGL. Of the two graph classes provided - in BGL: `adjacency_list` and `adjacency_matrix`, only `adjacency_list` is such a model. - So pls use `adjacency_list` to be your graph type. Note that there are seven template parameters for - `boost::adjacency_list`: `OutEdgeList`, `VertexList`, `Directed`, `VertexProperties`, `EdgeProperties`, - `GraphProperties`, `EdgeList`, of which we require `VertexProperties` be `Point_2` from \cgal, - and other parameters can be chosen freely. Here `Point_2` is passed directly as bundled properties - to `adjacency_list` because this makes our implementation much more straightforward than using property maps. - For detailed information about bundled properties, pls refer to - http://www.boost.org/doc/libs/1_58_0/libs/graph/doc/bundles.html. + \cgalModels `ConstructConeBasedSpanner_2` */ template class Construct_yao_graph_2 { @@ -86,13 +77,12 @@ private: public: /*! \brief Constructor. - * - * Constructs a `Construct_yao_graph_2` object. - * - * \param k Number of cones to divide space into - * \param initial_direction A direction denoting one of the rays dividing the - * cones. This allows arbitary rotations of the rays that divide - * the plane. (default: positive x-axis) + Constructs a `Construct_yao_graph_2` object. + + \param k Number of cones to divide space into + \param initial_direction A direction denoting one of the rays dividing the + cones. This allows arbitary rotations of the rays that divide + the plane. (default: positive x-axis) */ Construct_yao_graph_2 (unsigned int k, Direction_2 initial_direction = Direction_2(1,0) ) @@ -112,21 +102,20 @@ public: } /*! \brief Copy constructor. - * \param x another Construct_yao_graph_2 object to copy from. + \param x another Construct_yao_graph_2 object to copy from. */ Construct_yao_graph_2 (const Construct_yao_graph_2& x) : cone_number(x.cone_number), rays(x.rays) {} /*! \brief Operator to construct a Yao graph. - * - * This operator implements the algorithm for adding edges to build the Yao graph. - * The algorithm implemented is described in: - * Giri Narasimhan and Michiel Smid, Chapter 4: Spanners based on the Yao graph, Geometric Spanner Networks, - * Cambridge University Press, 2007. - * This algorithm has the complexity of O(n*log(n)), which is optimal. - * - * \param start[in] An iterator pointing to the first point (vertex). - * \param end[in] An iterator pointing to the place that passes the last point. - * \param g[out] The constructed graph object. + This operator implements the algorithm for adding edges to build the Yao graph. + The algorithm implemented is described in: + Giri Narasimhan and Michiel Smid, Chapter 4: Spanners based on the Yao graph, Geometric Spanner Networks, + Cambridge University Press, 2007. + This algorithm has the complexity of O(n*log(n)), which is optimal. + + \param start[in] An iterator pointing to the first point (vertex). + \param end[in] An iterator pointing to the place that passes the last point. + \param g[out] The constructed graph object. */ template Graph_& operator()(const PointInputIterator& start, @@ -157,8 +146,8 @@ public: } /*! \brief returns the vector of the directions of the rays dividing the plane. - * - * \return a vector of Direction_2 + + \return a vector of Direction_2 */ const std::vector& directions() const { return rays; @@ -166,7 +155,7 @@ public: protected: - /* \brief Construct edges in one cone bounded by two directions. + /* Construct edges in one cone bounded by two directions. \param cwBound The direction of the clockwise boundary of the cone. \param ccwBound The direction of the counter-clockwise boundary. diff --git a/Cone_spanners_2/include/CGAL/gnuplot_output_2.h b/Cone_spanners_2/include/CGAL/gnuplot_output_2.h index 5758b9e9205..81a10f4e51e 100644 --- a/Cone_spanners_2/include/CGAL/gnuplot_output_2.h +++ b/Cone_spanners_2/include/CGAL/gnuplot_output_2.h @@ -196,7 +196,7 @@ namespace CGAL { } // directed graphs - /*! Writing edge list to the gnuplot script for directed graphs */ + /* Writing edge list to the gnuplot script for directed graphs */ template struct Gnuplot_edges_2 { @@ -217,12 +217,12 @@ namespace CGAL { }; // Bidirectional graph, the same as the directed graph. - /*! Writing edge list to the gnuplot script for bidirectional graphs */ + /* Writing edge list to the gnuplot script for bidirectional graphs */ template struct Gnuplot_edges_2 : public Gnuplot_edges_2 {}; // Undirected graphs - /*! Writing edge list to the gnuplot script for undirected graphs */ + /* Writing edge list to the gnuplot script for undirected graphs */ template struct Gnuplot_edges_2 {