[doc][doxygen] introduce Distance group

doc/doxygen/modules.txt

@@ -8,3 +8,8 @@
  * \defgroup Common Common
  * \brief Common classes, functions, properties and concepts
  */
+
+/*!
+ * \defgroup Distance Distance
+ * \brief Functionality related to distance computations between geometrical objects.
+ */

frackit/distance/distance.hh

@@ -18,6 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
+ * \ingroup Distance
  * \brief Contains functionality for computing
  *        the distance between geometries.
  */
@@ -51,6 +52,7 @@ namespace Impl {
 }
 
 /*!
+ * \ingroup Distance
  * \brief Computes the distance between two TopoDS_Shape objects.
  * \param shape1 The first shape
  * \param shape2 The second shape
@@ -72,6 +74,7 @@ ctype computeDistance(const TopoDS_Shape& shape1,
 }
 
 /*!
+ * \ingroup Distance
  * \brief In the general case we compute the distance based on
  *        the basis of the BRep of the geometries. Overloads for
  *        geometries for which the distance can be computed more
@@ -102,7 +105,8 @@ computeDistance(const Geom1& geo1,
 }
 
 /*!
- * \brief Overload for one of the geometries being a shape object.
+ * \ingroup Distance
+ * \brief Computes the distance between a TopoDS_Shape and an internal geometry type.
  * \param shape The shape of one geometry
  * \param geo The second geometry
  * \param deflection The epsilon used in the BrepExtrema command
@@ -119,7 +123,8 @@ computeDistance(const TopoDS_Shape& shape,
 { return computeDistance(shape, OCCUtilities::getShape(geo), deflection, extFlag, extAlgo); }
 
 /*!
- * \brief Overload for one of the geometries being a shape object.
+ * \ingroup Distance
+ * \brief Computes the distance between an internal geometry type and a TopoDS_Shape.
  * \param geo The second geometry
  * \param shape The shape of one geometry
  * \param deflection The epsilon used in the BrepExtrema command
@@ -136,6 +141,7 @@ computeDistance(const Geom& geo,
 { return computeDistance(OCCUtilities::getShape(geo), shape, deflection, extFlag, extAlgo); }
 
 /*!
+ * \ingroup Distance
  * \brief Returns the euclidian distance between two points.
  * \param p1 The first point
  * \param p2 The second point
@@ -146,6 +152,7 @@ PromotedType<ctype1, ctype2> computeDistance(const Point<ctype1, worldDim>& p1,
 { return Vector<PromotedType<ctype1, ctype2>, worldDim>(p1, p2).length(); }
 
 /*!
+ * \ingroup Distance
  * \brief Returns the euclidian distance between a point and a line.
  * \param p The point
  * \param line The line
@@ -156,6 +163,7 @@ PromotedType<ctype1, ctype2> computeDistance(const Point<ctype1, worldDim>& p,
 { return Vector<PromotedType<ctype1, ctype2>, worldDim>(p, line.projection(p)).length(); }
 
 /*!
+ * \ingroup Distance
  * \brief Returns the euclidian distance between a line and a point.
  * \param line The line
  * \param p The point
@@ -166,6 +174,7 @@ PromotedType<ctype1, ctype2> computeDistance(const Line<ctype1, worldDim>& line,
 { return computeDistance(p, line); }
 
 /*!
+ * \ingroup Distance
  * \brief Returns the euclidian distance between a point and a segment.
  * \param p The point
  * \param seg The segment
@@ -188,6 +197,7 @@ PromotedType<ctype1, ctype2> computeDistance(const Point<ctype1, worldDim>& p,
 }
 
 /*!
+ * \ingroup Distance
  * \brief Returns the euclidian distance between a segment and a point.
  * \param seg The segment
  * \param p The point

frackit/distance/distancetoboundary.hh

@@ -18,6 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
+ * \ingroup Distance
  * \brief Contains functionality for computing the distance
  *        of a geometry to the boundary of another geometry.
  */
@@ -44,6 +45,7 @@
 namespace Frackit {
 
 /*!
+ * \ingroup Distance
  * \brief Compute the distance of a geometry
  *        to the boundary of another geometry.
  * \param geo1 The first geometry
@@ -51,6 +53,8 @@ namespace Frackit {
  * \param deflection The epsilon used in the BrepExtrema command
  * \param extFlag The flag passed to the BrepExtrema command (MIN/MAX/MINMAX)
  * \param extAlgo The algorithm passed to the BrepExtrema command (TREE/GRAD)
+ * \note This is the default overload throwing an error. Overloads have to be
+ *       implemented for pairs of geometries.
  */
 template<class Geo1, class Geo2>
 Impl::PCT<Geo1, Geo2>
@@ -68,6 +72,7 @@ computeDistanceToBoundary(const Geo1& geo1,
 }
 
 /*!
+ * \ingroup Distance
  * \brief Compute the distance of a geometry
  *        to the bounding ellipse of a disk.
  * \param geo The geometry
@@ -93,6 +98,7 @@ computeDistanceToBoundary(const Geo& geo,
 }
 
 /*!
+ * \ingroup Distance
  * \brief Compute the distance of a point
  *        to the bounding of a quadrilateral.
  * \param p The point
@@ -113,6 +119,7 @@ computeDistanceToBoundary(const Point<ctype1, 3>& p,
 }
 
 /*!
+ * \ingroup Distance
  * \brief Compute the distance of a geometry
  *        to the bounding circles of a cylinder surface.
  * \param geo The geometry
@@ -144,6 +151,7 @@ computeDistanceToBoundary(const Geo& geo,
 }
 
 /*!
+ * \ingroup Distance
  * \brief Compute the distance of a shape
  *        to the bounding ellipse of a disk.
  * \param shape The shape
@@ -167,6 +175,7 @@ ctype computeDistanceToBoundary(const TopoDS_Shape& shape,
 }
 
 /*!
+ * \ingroup Distance
  * \brief Compute the distance of a shape
  *        to the boundary of a TopoDS_Face.
  * \param shape The shape
@@ -192,6 +201,7 @@ ctype computeDistanceToBoundary(const TopoDS_Shape& shape,
 }
 
 /*!
+ * \ingroup Distance
  * \brief Compute the distance of a shape
  *        to the bounding wire of a quadrilateral.
  * \param shape The shape
@@ -215,6 +225,7 @@ ctype computeDistanceToBoundary(const TopoDS_Shape& shape,
 }
 
 /*!
+ * \ingroup Distance
  * \brief Compute the distance of a geometry
  *        to the boundary of a TopoDS_Face.
  * \param geo The geometry

frackit/distance/pointonboundary.hh

@@ -18,8 +18,10 @@
  *****************************************************************************/
 /*!
  * \file
+ * \ingroup Distance
  * \brief Contains functionality to evaluate if points are contained
- *        on the boundary of geometries.
+ *        on the boundary of geometries, i.e. if the distance to the
+ *        boundary is below a given numerical threshold.
  */
 #ifndef FRACKIT_POINT_ON_GEOMETRY_BOUNDARY_HH
 #define FRACKIT_POINT_ON_GEOMETRY_BOUNDARY_HH
@@ -43,10 +45,13 @@
 namespace Frackit {
 
 /*!
+ * \ingroup Distance
  * \brief Evaluate if a point lies on the boundary of a geometry.
  * \param p The point
  * \param geo The geometry
  * \param eps Epsilon value to be used for the check
+ * \note This is the default overload throwing an error. Overloads
+ *       have to be implemented for the different geometries.
  */
 template<class ctype1, int wd, class Geo, class ctype2>
 bool pointOnGeometryBoundary(const Point<ctype1, wd>& p, const Geo& geo, ctype2 eps)
@@ -58,6 +63,7 @@ bool pointOnGeometryBoundary(const Point<ctype1, wd>& p, const Geo& geo, ctype2
 }
 
 /*!
+ * \ingroup Distance
  * \brief Evaluate if a point lies on the boundary of a disk.
  * \param p The point
  * \param disk The disk
@@ -70,6 +76,7 @@ bool pointOnGeometryBoundary(const Point<ctype1, wd>& p,
 { return pointOnGeometry(p, disk.boundingEllipse(), eps); }
 
 /*!
+ * \ingroup Distance
  * \brief Evaluate if a point lies on the boundary of
  *        a quadrilateral in 3d space.
  * \param p The point
@@ -88,6 +95,7 @@ bool pointOnGeometryBoundary(const Point<ctype1, 3>& p,
 }
 
 /*!
+ * \ingroup Distance
  * \brief Evaluate if a point lies on the boundary of a cylinder surface.
  * \param p The point
  * \param cylSurface The cylinder surface
@@ -104,6 +112,7 @@ bool pointOnGeometryBoundary(const Point<ctype1, wd>& p,
 }
 
 /*!
+ * \ingroup Distance
  * \brief Evaluate if a point lies on the boundary of a face shape.
  * \param p The point
  * \param face The face shape
@@ -116,6 +125,7 @@ bool pointOnGeometryBoundary(const Point<ctype1, 3>& p,
 { return pointOnGeometry(p, BRepTools::OuterWire(face)); }
 
 /*!
+ * \ingroup Distance
  * \brief Evaluate if a point lies on the boundary of a geometry.
  * \param p The point
  * \param geo The geometry

frackit/distance/pointongeometry.hh

@@ -18,7 +18,9 @@
  *****************************************************************************/
 /*!
  * \file
- * \brief Contains functionality to evaluate if points are contained on geometries.
+ * \ingroup Distance
+ * \brief Contains functionality to evaluate if points are contained
+ *        on geometries, i.e. if the distance is below a numerical threshold.
  */
 #ifndef FRACKIT_POINT_ON_GEOMETRY_HH
 #define FRACKIT_POINT_ON_GEOMETRY_HH
@@ -34,6 +36,7 @@
 namespace Frackit {
 
 /*!
+ * \ingroup Distance
  * \brief Evaluate if a point lies on a geometry.
  * \param p The point
  * \param geo The geometry
@@ -48,6 +51,7 @@ bool pointOnGeometry(const Point<ctype1, wd>& p, const Geo& geo, ctype2 eps)
 }
 
 /*!
+ * \ingroup Distance
  * \brief Evaluate if a point lies on a shape.
  * \param p The point
  * \param shape The shape
@@ -61,6 +65,7 @@ bool pointOnGeometry(const Point<ctype1, 3>& p, const Shape& shape, ctype2 eps)
 }
 
 /*!
+ * \ingroup Distance
  * \brief Evaluate if a point lies on a geometry.
  * \param p The point
  * \param geo The geometry