add documentation and rename file

Polygon_mesh_processing/doc/Polygon_mesh_processing/PackageDescription.txt

@@ -8,6 +8,7 @@
 /// \defgroup keep_connected_components_grp CGAL::keep_connected_components()
 /// \ingroup PkgPolygonMeshProcessing
 /// \defgroup remove_connected_components_grp CGAL::remove_connected_components()
+/// \defgroup measure_grp Geometric Measure functions
 /// \ingroup PkgPolygonMeshProcessing
 
 /*!
@@ -84,6 +85,12 @@ and provides a list of the parameters that are used in this package.
 - \link keep_connected_components_grp `CGAL::Polygon_mesh_processing::keep_connected_components()` \endlink
 - \link remove_connected_components_grp `CGAL::Polygon_mesh_processing::remove_connected_components()` \endlink
 
+## Geometric Measure functions
+- \link measure_grp `CGAL::Polygon_mesh_processing::area()` \endlink
+- \link measure_grp `CGAL::Polygon_mesh_processing::length()` \endlink
+- \link measure_grp `CGAL::Polygon_mesh_processing::border_length()` \endlink
+
+
 ## Miscellaneous ##
 - `CGAL::Polygon_mesh_slicer`
 

Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/measure.h

@@ -18,8 +18,8 @@
 //
 // Author(s)     : Andreas Fabri
 
-#ifndef CGAL_POLYGON_MESH_PROCESSING_MEASURE_SIMPLICES_H
-#define CGAL_POLYGON_MESH_PROCESSING_MEASURE_SIMPLICES_H
+#ifndef CGAL_POLYGON_MESH_PROCESSING_MEASURE_H
+#define CGAL_POLYGON_MESH_PROCESSING_MEASURE_H
 
 #include <CGAL/boost/graph/iterator.h>
 #include <CGAL/boost/graph/helpers.h>
@@ -33,6 +33,24 @@ namespace CGAL {
 
 namespace Polygon_mesh_processing {
 
+  /**
+  * \ingroup measure_grp
+  * computes the length of a halfedge of a given polygon mesh.
+  *
+  * @tparam PolygonMesh a model of `HalfedgeGraph` that has an internal property map
+  *         for `boost::vertex_point_t`
+  * @tparam NamedParameters a sequence of \ref namedparameters
+  *
+  * @param h the halfedge of which the length is computed
+  * @param pmesh the polygon mesh to which `h` belongs
+  * @param np optional sequence of \ref namedparameters among the ones listed below
+  *
+  * \cgalNamedParamsBegin
+  *    \cgalParamBegin{vertex_point_map} the property map with the points associated to the vertices of `pmesh` \cgalParamEnd
+  * \cgalNamedParamsEnd
+  *
+  * @sa `border_length()`
+  */
   template<typename PolygonMesh,
            typename NamedParameters>
   double length(typename boost::graph_traits<PolygonMesh>::halfedge_descriptor h
@@ -59,6 +77,26 @@ namespace Polygon_mesh_processing {
       CGAL::Polygon_mesh_processing::parameters::all_default());
   }
 
+  /**
+  * \ingroup measure_grp
+  * computes the length of the border polyline
+  * that contains a given border halfedge.
+  *
+  * @pre `h` is a border halfedge
+  * @tparam PolygonMesh a model of `HalfedgeGraph` that has an internal property map
+  *         for `boost::vertex_point_t`
+  * @tparam NamedParameters a sequence of \ref namedparameters
+  *
+  * @param h a halfedge of the border polyline of which the length is computed
+  * @param pmesh the polygon mesh to which `h` belongs
+  * @param np optional sequence of \ref namedparameters among the ones listed below
+  *
+  * \cgalNamedParamsBegin
+  *    \cgalParamBegin{vertex_point_map} the property map with the points associated to the vertices of `pmesh` \cgalParamEnd
+  * \cgalNamedParamsEnd
+  *
+  * @sa `length()`
+  */
   template<typename PolygonMesh,
            typename NamedParameters>
   double
@@ -66,6 +104,8 @@ namespace Polygon_mesh_processing {
               , const PolygonMesh& pmesh
               , const NamedParameters& np)
   {
+    CGAL_precondition(is_border(h, pmesh));
+
     double result = 0.;
     BOOST_FOREACH(typename boost::graph_traits<PolygonMesh>::halfedge_descriptor haf,
                   halfedges_around_face(h, pmesh))
@@ -85,6 +125,22 @@ namespace Polygon_mesh_processing {
   }
 
 
+  /**
+  * \ingroup measure_grp
+  * computes the area of a face of a given polygon mesh.
+  *
+  * @tparam PolygonMesh a model of `HalfedgeGraph` that has an internal property map
+  *         for `boost::vertex_point_t`
+  * @tparam NamedParameters a sequence of \ref namedparameters
+  *
+  * @param f the face of which the area is computed
+  * @param pmesh the polygon mesh to which `f` belongs
+  * @param np optional sequence of \ref namedparameters among the ones listed below
+  *
+  * \cgalNamedParamsBegin
+  *    \cgalParamBegin{vertex_point_map} the property map with the points associated to the vertices of `pmesh` \cgalParamEnd
+  * \cgalNamedParamsEnd
+  */
   template<typename PolygonMesh,
            typename NamedParameters>
   double area(typename boost::graph_traits<PolygonMesh>::face_descriptor f
@@ -116,6 +172,25 @@ namespace Polygon_mesh_processing {
       CGAL::Polygon_mesh_processing::parameters::all_default());
   }
 
+  /**
+  * \ingroup measure_grp
+  * computes the area of a range of faces of a given polygon mesh.
+  *
+  * @tparam FaceRange range of `boost::graph_traits<PolygonMesh>::%face_descriptor`,
+          model of `Range`.
+          Its iterator type is `InputIterator`.
+  * @tparam PolygonMesh a model of `HalfedgeGraph` that has an internal property map
+  *         for `boost::vertex_point_t`
+  * @tparam NamedParameters a sequence of \ref namedparameters
+  *
+  * @param face_range the face range of which the area is computed
+  * @param pmesh the polygon mesh to which the faces of `face_range` belong
+  * @param np optional sequence of \ref namedparameters among the ones listed below
+  *
+  * \cgalNamedParamsBegin
+  *    \cgalParamBegin{vertex_point_map} the property map with the points associated to the vertices of `pmesh` \cgalParamEnd
+  * \cgalNamedParamsEnd
+  */
   template<typename FaceRange,
            typename PolygonMesh,
            typename NamedParameters>
@@ -142,4 +217,4 @@ namespace Polygon_mesh_processing {
 }
 }
 
-#endif // CGAL_POLYGON_MESH_PROCESSING_MEASURE_SIMPLICES_H
+#endif // CGAL_POLYGON_MESH_PROCESSING_MEASURE_H

Polygon_mesh_processing/test/Polygon_mesh_processing/measures_test.cpp

@@ -7,7 +7,7 @@
 #include <CGAL/Surface_mesh.h>
 #include <CGAL/boost/graph/properties_Surface_mesh.h>
 
-#include <CGAL/Polygon_mesh_processing/dimensions.h>
+#include <CGAL/Polygon_mesh_processing/measure.h>
 
 #include <iostream>
 #include <fstream>