Merge branch 'feature/doxygen-groups' into 'master'

Feature/doxygen groups

See merge request DennisGlaeser/frackit!44

doc/doxygen/Doxyfile.in

@@ -790,7 +790,11 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/frackit/ @CMAKE_CURRENT_SOURCE_DIR@/test
+INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/doc/doxygen/mainpage.txt  \
+                         @CMAKE_CURRENT_SOURCE_DIR@/doc/doxygen/modules.txt  \
+                         @CMAKE_CURRENT_SOURCE_DIR@/frackit/  \
+                         @CMAKE_CURRENT_SOURCE_DIR@/test/
+
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

doc/doxygen/mainpage.txt

+/*!
+ * \file
+ * \brief documentation for the doxygen main page
+ */

doc/doxygen/modules.txt

+/*!
+ * \file
+ * \brief This file contains all module definitions for the doxygen documentation.
+ */
+
+/*!
+ * \defgroup Common Common
+ * \brief Common classes, functions, properties and concepts
+ */
+
+/*!
+ * \defgroup EntityNetwork Entity Networks
+ * \brief Classes, functions and concepts related to networks of geometrical entities.
+ */
+
+    /*!
+     * \ingroup EntityNetwork
+     * \defgroup Constraints Constraints
+     * \brief Classes and functions related to the enforcement
+     *        geometric constraints (distance, intersection angle etc)
+     *        between entities in entity networks.
+     */
+
+/*!
+ * \defgroup Geometry Geometry
+ * \brief Classes that define basic geometrical objects.
+ */
+
+    /*!
+     * \ingroup Geometry
+     * \defgroup GeometryUtilities Geometry Utilities
+     * \brief Utility functionality for geometrical objects.
+     */
+
+    /*!
+     * \ingroup Geometry
+     * \defgroup Intersection Intersection
+     * \brief Classes and functions related to intersections between geometries.
+     */
+
+    /*!
+     * \ingroup Geometry
+     * \defgroup Distance Distance
+     * \brief Functionality related to distance computations between geometrical objects.
+     */
+
+    /*!
+     * \ingroup Geometry
+     * \defgroup Magnitude Magnitude
+     * \brief Functionality related to magnitude (length/area/volume) computations of geometrical objects.
+     */
+
+    /*!
+     * \ingroup Geometry
+     * \defgroup Sampling Sampling
+     * \brief Functionality related to random generation (sampling) of geometries.
+     */
+
+/*!
+ * \defgroup OpenCascade OpenCascade
+ * \brief Utility functions for communication with the OpenCascade library.
+ */
+
+/*!
+ * \defgroup IO Input-Output
+ * \brief Classes and functions for file input/output.
+ */
+
+/*!
+ * \defgroup Precision Precision
+ * \brief Definitions of tolerance values to be used for floating point comparisons.
+ */

frackit/common/extractctype.hh

@@ -18,6 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
+ * \ingroup Common
  * \brief Type traits to extract the coordinate type of geometric objects.
  */
 #ifndef FRACKIT_COMMON_COORDINATE_TYPE_HH
@@ -37,6 +38,7 @@
 namespace Frackit {
 
 /*!
+ * \ingroup Common
  * \brief Traits class to extract the coordinate type from a geometry.
  * \note This is the specialization used for internal geometry types
  *       which carry the information of the coordinate type themselves.

frackit/common/extractdimension.hh

@@ -18,6 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
+ * \ingroup Common
  * \brief Type traits to extract the dimensionality of geometric objects.
  */
 #ifndef FRACKIT_COMMON_EXTRACT_DIMENSION_HH
@@ -37,6 +38,7 @@
 namespace Frackit {
 
 /*!
+ * \ingroup Common
  * \brief Traits class to extract the dimensionalty of a geometry.
  * \note This is the specialization used for internal geometry types
  *       which carry the information of the dimensions themselves.

frackit/common/id.hh

@@ -18,6 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
+ * \ingroup Common
  * \brief Simple wrapper class to define ids/indices.
  */
 #ifndef FRACKIT_ID_HH
@@ -26,6 +27,7 @@
 namespace Frackit {
 
 /*!
+ * \ingroup Common
  * \brief Simple wrapper class to define ids/indices.
  *        This can be used wherever indices are passed
  *        to interfaces to avoid implicit conversion of

frackit/common/idpair.hh

@@ -18,6 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
+ * \ingroup Common
  * \brief Simple class to define pairs of ids.
  */
 #ifndef FRACKIT_ID_PAIR_HH
@@ -30,6 +31,7 @@
 namespace Frackit {
 
 /*!
+ * \ingroup Common
  * \brief Simple class to define pairs of ids.
  */
 class IdPair

frackit/common/math.hh

@@ -18,7 +18,8 @@
  *****************************************************************************/
 /*!
  * \file
- * \brief Define some mathematical functions
+ * \ingroup Common
+ * \brief Defines some mathematical functions.
  */
 #ifndef FRACKIT_MATH_HH
 #define FRACKIT_MATH_HH
@@ -32,6 +33,7 @@
 namespace Frackit {
 
 /*!
+ * \ingroup Common
  * \brief Returns the vector resulting from the cross product
  *        of two 3-dimensional vectors.
  */
@@ -45,6 +47,7 @@ Vector<ctype, 3> crossProduct(const Vector<ctype, 3>& v1,
 }
 
 /*!
+ * \ingroup Common
  * \brief Returns the scalar resulting from the cross product
  *        of two 2-dimensional vectors.
  */
@@ -54,6 +57,7 @@ ctype crossProduct(const Vector<ctype, 2>& v1,
 { return v1.x()*v2.y() - v1.y()*v2.x(); }
 
 /*!
+ * \ingroup Common
  * \brief Returns the scalar resulting from the box product
  *        of three 3-dimensional vectors.
  */
@@ -64,6 +68,7 @@ ctype boxProduct(const Vector<ctype, 3>& v1,
 { return v1*crossProduct(v2, v3); }
 
 /*!
+ * \ingroup Common
  * \brief Returns true if the given 3-dimensional
  *        vectors form a right-hand system.
  */
@@ -79,6 +84,7 @@ bool isRightHandSystem(const Vector<ctype, 3>& v1,
 }
 
 /*!
+ * \ingroup Common
  * \brief Converts a given angle in radians to degrees.
  */
 template<class ctype>
@@ -86,6 +92,7 @@ ctype toDegrees(const ctype radians)
 { return radians*180.0/M_PI; }
 
 /*!
+ * \ingroup Common
  * \brief Converts a given angle in degrees to radians.
  */
 template<class ctype>
@@ -93,6 +100,7 @@ ctype toRadians(const ctype degrees)
 { return degrees*M_PI/180.0; }
 
 /*!
+ * \ingroup Common
  * \brief Rotate a vector around an axis by a given angle.
  * \param v The vector to be rotated
  * \param axis The rotation axis
@@ -124,6 +132,7 @@ void rotate(Vector<ctype, 3>& v,
 }
 
 /*!
+ * \ingroup Common
  * \brief Rotate several vectors around an axis by a given angle.
  * \param vectors The vectors to be rotated
  * \param axis The rotation axis

frackit/common/promotedtype.hh

@@ -18,6 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
+ * \ingroup Common
  * \brief Determines the type that results from arithmetic
  *        operations on two different number types.
  */
@@ -29,9 +30,10 @@
 namespace Frackit {
 
 /*!
-* \brief Determines the type that results from arithmetic
-*        operations on two different number types.
-*/
+ * \ingroup Common
+ * \brief Determines the type that results from arithmetic
+ *        operations on two different number types.
+ */
 template<class T1, class T2>
 struct PromotionTraits
 {
@@ -43,8 +45,9 @@ template<class T1>
 struct PromotionTraits<T1,T1> { typedef T1 PromotedType; };
 
 /*!
-* \brief Convenience alias to get the promoted type
-*/
+ * \ingroup Common
+ * \brief Convenience alias to get the promoted type
+ */
 template<class T1, class T2>
 using PromotedType = typename PromotionTraits<T1, T2>::PromotedType;
 

frackit/common/typetraits.hh

@@ -18,6 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
+ * \ingroup Common
  * \brief Defines classes to obtain type information at compile-time.
  */
 #ifndef FRACKIT_COMMON_TYPE_TRAITS_HH
@@ -28,6 +29,7 @@
 namespace Frackit {
 
 /*!
+ * \ingroup Common
  * \brief Helper struct to detect if a type T
  *        is contained in a parameter pack Ts
  * \tparam T The type of which an ocurrence in the pack is to be checked

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

frackit/entitynetwork/constraints.hh

@@ -18,6 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
+ * \ingroup Constraints
  * \brief Class that enforces geometric
  *        constraints on networks of entities.
  */
@@ -53,14 +54,16 @@ template<class ST = double,
 class EntityNetworkConstraints;
 
 /*!
- * \brief Convenience function to construct an instance
- *        of the constraints class using the default engines
+ * \ingroup Constraints
+ * \brief Convenience function to construct an instance of
+ *        the constraints class using the default template arguments.
  */
 template<class ST = double>
 EntityNetworkConstraints<ST> makeDefaultConstraints()
 { return EntityNetworkConstraints<ST>(IntersectionAngle<ST>()); }
 
 /*!
+ * \ingroup Constraints
  * \brief Class which defines and checks constraints on
  *        the geometric relationships between entities of
  *        a network. As constraints one can define:

frackit/entitynetwork/constraintsmatrix.hh

@@ -18,6 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
+ * \ingroup Constraints
  * \brief Class that allows defining a matrix of constraints.
  *        This is useful in contexts where multiple entity sets
  *        are defined, and where different constraints should be
@@ -38,6 +39,7 @@
 namespace Frackit {
 
 /*!
+* \ingroup Constraints
  * \brief Class that allows defining a matrix of constraints.
  *        For each constraint that is defined, a list of id pairs
  *        is passed that defines between which ids (representing

frackit/entitynetwork/containedentitynetwork.hh

@@ -18,6 +18,7 @@
  *****************************************************************************/
  /*!
   * \file
+  * \ingroup EntityNetwork
   * \brief Class representing a network of entities, contained
   *        in (possibly multiple) sub-domains. Sub-networks might
   *        be defined on each sub-domain.
@@ -38,6 +39,7 @@
 namespace Frackit {
 
 /*!
+ * \ingroup EntityNetwork
  * \relates ContainedEntityNetworkBuilder
  * \brief Class representing a network of entities, contained
  *        in (possibly multiple) sub-domains. Sub-networks might

frackit/entitynetwork/containedentitynetworkinterface.hh

@@ -18,6 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
+ * \ingroup EntityNetwork
  * \brief Interface defining networks of entities contained
  *        in (possibly multiple) sub-domains.
  */
@@ -35,6 +36,7 @@
 namespace Frackit {
 
 /*!
+ * \ingroup EntityNetwork
  * \brief Interface defining networks of entities contained
  *        in (possibly multiple) sub-domains.
  */

frackit/entitynetwork/entitynetwork.hh

@@ -18,6 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
+ * \ingroup EntityNetwork
  * \brief Class representing a network of entities,
  *        consisting of fragments of primary entities.
  */
@@ -33,6 +34,7 @@
 namespace Frackit {
 
 /*!
+ * \ingroup EntityNetwor
  * \relates EntityNetworkBuilder
  * \brief Class representing a network of entities,
  *        consisting of fragments of primary entities.

frackit/entitynetwork/entitynetworkinterface.hh

@@ -18,6 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
+ * \ingroup EntityNetwork
  * \brief Interface defining networks of entities.
  */
 #ifndef FRACKIT_ENTITY_NETWORK_INTERFACE_HH
@@ -30,6 +31,7 @@
 namespace Frackit {
 
 /*!
+ * \ingroup EntityNetwork
  * \brief Interface defining networks of entities.
  */
 class EntityNetworkInterface