songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve the comments

This commit is contained in:
Weisheng Si 2015-06-23 08:39:35 +10:00
parent decb515703
commit 74b8893cb0
5 changed files with 69 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
Cone_spanners_2/doc/Cone_spanners_2/Concepts/ConstructConeBasedSpanner_2.h
View File

@ -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.

23
Cone_spanners_2/include/CGAL/Compute_cone_boundaries_2.h
View File

@ -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 <typename Kernel_>
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<Exact_predicates_exact_constructions_kernel_with_sqrt> {
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

61
Cone_spanners_2/include/CGAL/Construct_theta_graph_2.h
View File

@ -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 <typename Kernel_, typename Graph_>
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 <typename PointInputIterator>
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<Direction_2>& 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.

59
Cone_spanners_2/include/CGAL/Construct_yao_graph_2.h
View File

@ -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 <typename Kernel_, typename Graph_>
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 <typename PointInputIterator>
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<Direction_2>& 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.

6
Cone_spanners_2/include/CGAL/gnuplot_output_2.h
View File

@ -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 <typename Graph>
struct Gnuplot_edges_2<Graph, boost::directedS> {
@ -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 <typename Graph>
struct Gnuplot_edges_2<Graph, boost::bidirectionalS> : public Gnuplot_edges_2<Graph, boost::directedS> {};
// Undirected graphs
/*! Writing edge list to the gnuplot script for undirected graphs */
/* Writing edge list to the gnuplot script for undirected graphs */
template <typename Graph>
struct Gnuplot_edges_2<Graph, boost::undirectedS> {