Merge branch 'feature/doxygen' into 'master'

Feature/doxygen

See merge request DennisGlaeser/frackit!9

CMakeLists.txt

@@ -80,10 +80,35 @@ else()
     message(FATAL_ERROR "OpenCascade sources not found")
 endif()
 
+# indicate the documentation build as an option and set it to ON by default
+option(BUILD_DOC "Build documentation" ON)
+
+# check if Doxygen is installed
+find_package(Doxygen)
+if (DOXYGEN_FOUND)
+    # set input and output files
+    set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/doc/doxygen/Doxyfile.in)
+    set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/doc/doxygen/Doxyfile)
+
+    # request to configure the file
+    configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
+    message("Doxygen build started")
+
+    # note the option ALL which allows to build the docs together with the application
+    add_custom_target( doc_doxygen
+                       COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
+                       WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                       COMMENT "Generating API documentation with Doxygen"
+                       VERBATIM )
+else (DOXYGEN_FOUND)
+  message("Doxygen need to be installed to generate the doxygen documentation")
+endif (DOXYGEN_FOUND)
+
 # include the sources
 include_directories( ${CMAKE_SOURCE_DIR} )
 
 # include subdirectories
 add_subdirectory(cmake)
+add_subdirectory(doc)
 add_subdirectory(frackit)
 add_subdirectory(test)

doc/CMakeLists.txt

+add_subdirectory(doxygen)

frackit/geometry/ellipse.hh

@@ -64,7 +64,7 @@ public:
     //! pull up base class' constructor
     using ParentType::ParentType;
 
-    //! \todo TODO doc me.
+    //! Return the name of this geometry
     static std::string name() { return "Ellipse"; }
 
     /*!

frackit/geometry/point.hh

@@ -36,81 +36,78 @@ namespace Frackit {
 // Forwad declaration
 template<class CT, int wd> class Vector;
 
-    namespace Impl {
+/*!
+ * \brief Base class for Point implementations.
+ * \tparam Impl The actual vector class implementation
+ * \tparam CT The type used for coordinates
+ * \tparam wd The dimension of the space
+ */
+template<class Impl, class CT, int wd>
+class PointBase
+{
+
+public:
+    //! export dimensionality
+    static constexpr int myDimension() { return 0; };
+    static constexpr int worldDimension() { return wd; };
+
+    //! export type used for coordinates
+    using ctype = CT;
 
     /*!
-     * \brief Base class for Point implementations.
-     * \tparam Impl The actual vector class implementation
-     * \tparam CT The type used for coordinates
-     * \tparam wd The dimension of the space
+     * \brief Default constructor. Creates a point at the origin.
      */
-    template<class Impl, class CT, int wd>
-    class PointBase
+    PointBase()
     {
+        std::fill(coordinates_.begin(), coordinates_.end(), 0.0);
+    }
 
-    public:
-        //! export dimensionality
-        static constexpr int myDimension() { return 0; };
-        static constexpr int worldDimension() { return wd; };
-
-        //! export type used for coordinates
-        using ctype = CT;
-
-        /*!
-         * \brief Default constructor. Creates a point at the origin.
-         */
-        PointBase()
-        {
-            std::fill(coordinates_.begin(), coordinates_.end(), 0.0);
-        }
-
-        /*!
-         * \brief Construction from an initializer list.
-         * \param l The initializer list containing the coordinates
-         */
-        PointBase(const std::initializer_list<CT>& l)
-        {
-            const auto minDim = std::min(static_cast<std::size_t>(wd), l.size());
-            std::copy_n( l.begin(), minDim, coordinates_.begin());
-        }
-
-        //! Return the name of this geometry class
-        static std::string name()
-        { return "Point"; }
-
-        //! Returns true if the given point is equal to this one
-        bool isEqual(const Impl& other, ctype eps) const
-        { return Vector<ctype, wd>(asImp_(), other).squaredLength() < eps*eps; }
-
-        //! Returns true if the given point is equal to this one (default eps)
-        bool isEqual(const Impl& other) const
-        {
-            const auto scale = Vector<ctype, wd>(Impl(), asImp_()).length();
-            const auto eps = Precision<ctype>::confusion()*scale;
-            return isEqual(other, eps);
-        }
-
-    protected:
-        //! Provide access to the underlying coordinates
-        ctype operator[] (unsigned int i) const
-        {
-            assert(i < coordinates_.size());
-            return coordinates_[i];
-        }
-
-        //! Provide access to the coordinate storage
-        std::array<ctype, wd>& coordinates()
-        { return coordinates_; }
-
-        //! Returns the implementation (static polymorphism)
-        Impl &asImp_() { return *static_cast<Impl*>(this); }
-        //! \copydoc asImp_()
-        const Impl &asImp_() const { return *static_cast<const Impl*>(this); }
-
-    private:
-        std::array<ctype, wd> coordinates_;
-    };
-    } // end namespace Impl
+    /*!
+     * \brief Construction from an initializer list.
+     * \param l The initializer list containing the coordinates
+     */
+    PointBase(const std::initializer_list<CT>& l)
+    {
+        const auto minDim = std::min(static_cast<std::size_t>(wd), l.size());
+        std::copy_n( l.begin(), minDim, coordinates_.begin());
+    }
+
+    //! Return the name of this geometry class
+    static std::string name()
+    { return "Point"; }
+
+    //! Returns true if the given point is equal to this one
+    bool isEqual(const Impl& other, ctype eps) const
+    { return Vector<ctype, wd>(asImp_(), other).squaredLength() < eps*eps; }
+
+    //! Returns true if the given point is equal to this one (default eps)
+    bool isEqual(const Impl& other) const
+    {
+        const auto scale = Vector<ctype, wd>(Impl(), asImp_()).length();
+        const auto eps = Precision<ctype>::confusion()*scale;
+        return isEqual(other, eps);
+    }
+
+protected:
+    //! Provide access to the underlying coordinates
+    ctype operator[] (unsigned int i) const
+    {
+        assert(i < coordinates_.size());
+        return coordinates_[i];
+    }
+
+    //! Provide access to the coordinate storage
+    std::array<ctype, wd>& coordinates()
+    { return coordinates_; }
+
+    //! Returns the implementation (static polymorphism)
+    Impl &asImp_() { return *static_cast<Impl*>(this); }
+    //! \copydoc asImp_()
+    const Impl &asImp_() const { return *static_cast<const Impl*>(this); }
+
+private:
+    std::array<ctype, wd> coordinates_;
+};
 
 /*!
  * \brief Point class implementation.
@@ -125,10 +122,10 @@ class Point;
  */
 template<class CT>
 class Point<CT, 1>
-: public Impl::PointBase< Point<CT, 1>, CT, 1 >
+: public PointBase< Point<CT, 1>, CT, 1 >
 {
     using ThisType = Point<CT, 1>;
-    using ParentType = Impl::PointBase<ThisType, CT, 1>;
+    using ParentType = PointBase<ThisType, CT, 1>;
 
 public:
     //! pull up base class' constructors
@@ -182,10 +179,10 @@ public:
  */
 template<class CT>
 class Point<CT, 2>
-: public Impl::PointBase< Point<CT, 2>, CT, 2 >
+: public PointBase< Point<CT, 2>, CT, 2 >
 {
     using ThisType = Point<CT, 2>;
-    using ParentType = Impl::PointBase<ThisType, CT, 2>;
+    using ParentType = PointBase<ThisType, CT, 2>;
 
 public:
     //! pull up base class' constructors
@@ -244,10 +241,10 @@ public:
  */
 template<class CT>
 class Point<CT, 3>
-: public Impl::PointBase< Point<CT, 3>, CT, 3 >
+: public PointBase< Point<CT, 3>, CT, 3 >
 {
     using ThisType = Point<CT, 3>;
-    using ParentType = Impl::PointBase<ThisType, CT, 3>;
+    using ParentType = PointBase<ThisType, CT, 3>;
 
 public:
     //! pull up base class' constructors

frackit/geometry/vector.hh

@@ -51,8 +51,11 @@ class Vector;
 template<class CT, int wd> class Point;
 template<class CT, int wd> class Direction;
 
+// Hide implementation from Doxygen
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 // namespace with implementation details
-namespace Impl {
+namespace VectorImpl {
 
     /*!
      * \brief Computes the scalar product between two 1d vectors.
@@ -124,122 +127,123 @@ namespace Impl {
     template<class CT1, class CT2>
     Vector<CT1, 3> subtractVectors(const Vector<CT1, 3>& v1, const Vector<CT2, 3>& v2)
     { return {v1.x()-v2.x(), v1.y()-v2.y(), v1.z()-v2.z()}; }
+} // end namespace VectorImpl
+#endif // DOXYGEN_SHOULD_SKIP_THIS
+
+/*!
+ * \brief Base class of the dimension-specific Vector implementations.
+ * \tparam Impl The actual vector class implementation
+ * \tparam CT The type used for coordinates
+ * \tparam wd The dimension of the space
+ */
+template<class Impl, class CoordType, int wd>
+class VectorBase
+{
+
+public:
+    //! export dimensionality
+    static constexpr int myDimension() { return 1; };
+    static constexpr int worldDimension() { return wd; };
+
+    //! export type used for coordinates
+    using ctype = CoordType;
+
+    //! export underlying point type
+    using Point = typename Frackit::Point<ctype, wd>;
+    using Vector = typename Frackit::Vector<ctype, wd>;
+    using Direction = typename Frackit::Direction<ctype, wd>;
 
     /*!
-     * \brief Base class of the dimension-specific Vector implementations.
-     * \tparam Impl The actual vector class implementation
-     * \tparam CT The type used for coordinates
-     * \tparam wd The dimension of the space
+     * \brief Constructs a vector from a single scalar value
+     *        assigning this value to each coordinate direction.
+     * \param value The coordinate value
      */
-    template<class Impl, class CoordType, int wd>
-    class VectorBase
+    VectorBase(ctype value = 0.0)
     {
+        std::fill(coordinates_.begin(), coordinates_.end(), value);
+    }
 
-    public:
-        //! export dimensionality
-        static constexpr int myDimension() { return 1; };
-        static constexpr int worldDimension() { return wd; };
-
-        //! export type used for coordinates
-        using ctype = CoordType;
-
-        //! export underlying point type
-        using Point = typename Frackit::Point<ctype, wd>;
-        using Vector = typename Frackit::Vector<ctype, wd>;
-        using Direction = typename Frackit::Direction<ctype, wd>;
-
-        /*!
-         * \brief Constructs a vector from a single scalar value
-         *        assigning this value to each coordinate direction.
-         * \param value The coordinate value
-         */
-        VectorBase(ctype value = 0.0)
-        {
-            std::fill(coordinates_.begin(), coordinates_.end(), value);
-        }
-
-        /*!
-         * \brief Constructs a vector from an initializer list.
-         * \param l The initializer list containing the coordinates
-         */
-        VectorBase(const std::initializer_list<ctype>& l)
-        {
-            const auto minSize = std::min(static_cast<std::size_t>(wd), l.size());
-            std::copy_n( l.begin(), minSize, coordinates_.begin() );
-        }
-
-        //! Return the name of this geometry class
-        static std::string name()
-        { return "Vector"; }
-
-        //! Return the squared length of the vector
-        ctype squaredLength() const
-        {
-            ctype result = 0;
-            for (unsigned int i = 0; i < wd; ++i)
-                result += coordinates_[i]*coordinates_[i];
-            return result;
-        }
-
-        //! Return the length of the vector
-        ctype length() const
-        {
-            using std::sqrt;
-            return sqrt(squaredLength());
-        }
-
-        //! Scalar product with another vector
-        template<class CT>
-        ctype operator*(const Frackit::Vector<CT, wd>& other) const
-        { return scalarProduct(asImp_(), other); }
-
-        //! Add vector to this one
-        template<class CT>
-        Impl operator+(const Frackit::Vector<CT, wd>& other) const
-        { return sumVectors(asImp_(), other); }
-
-        //! Subtract vector from this one
-        template<class CT>
-        Impl operator-(const Frackit::Vector<CT, wd>& other) const
-        { return subtractVectors(asImp_(), other); }
-
-        //! Product of this vector with a scalar
-        template<class CT>
-        Impl& operator*=(CT value)
-        {
-            for (auto& coord : coordinates_)
-                coord *= value;
-            return asImp_();
-        }
-
-        //! Division of this vector with a scalar
-        template<class CT>
-        Impl& operator/=(CT value)
-        {
-            for (auto& coord : coordinates_)
-                coord /= value;
-            return asImp_();
-        }
-
-    protected:
-        //! Provide access to the coordinates of the vector
-        ctype operator[] (unsigned int coordIdx) const
-        { return coordinates_[coordIdx]; }
-
-        //! Provide access to the coordinates of the vector
-        std::array<ctype, wd>& data()
-        { return coordinates_; }
-
-        //! Returns the implementation (static polymorphism)
-        Impl &asImp_() { return *static_cast<Impl*>(this); }
-        //! \copydoc asImp_()
-        const Impl &asImp_() const { return *static_cast<const Impl*>(this); }
-
-    private:
-        // storage of the coordinates
-        std::array<ctype, wd> coordinates_;
-    };
-} // end namespace Impl
+    /*!
+     * \brief Constructs a vector from an initializer list.
+     * \param l The initializer list containing the coordinates
+     */
+    VectorBase(const std::initializer_list<ctype>& l)
+    {
+        const auto minSize = std::min(static_cast<std::size_t>(wd), l.size());
+        std::copy_n( l.begin(), minSize, coordinates_.begin() );
+    }
+
+    //! Return the name of this geometry class
+    static std::string name()
+    { return "Vector"; }
+
+    //! Return the squared length of the vector
+    ctype squaredLength() const
+    {
+        ctype result = 0;
+        for (unsigned int i = 0; i < wd; ++i)
+            result += coordinates_[i]*coordinates_[i];
+        return result;
+    }
+
+    //! Return the length of the vector
+    ctype length() const
+    {
+        using std::sqrt;
+        return sqrt(squaredLength());
+    }
+
+    //! Scalar product with another vector
+    template<class CT>
+    ctype operator*(const Frackit::Vector<CT, wd>& other) const
+    { return VectorImpl::scalarProduct(asImp_(), other); }
+
+    //! Add vector to this one
+    template<class CT>
+    Impl operator+(const Frackit::Vector<CT, wd>& other) const
+    { return VectorImpl::sumVectors(asImp_(), other); }
+
+    //! Subtract vector from this one
+    template<class CT>
+    Impl operator-(const Frackit::Vector<CT, wd>& other) const
+    { return VectorImpl::subtractVectors(asImp_(), other); }
+
+    //! Product of this vector with a scalar
+    template<class CT>
+    Impl& operator*=(CT value)
+    {
+        for (auto& coord : coordinates_)
+            coord *= value;
+        return asImp_();
+    }
+
+    //! Division of this vector with a scalar
+    template<class CT>
+    Impl& operator/=(CT value)
+    {
+        for (auto& coord : coordinates_)
+            coord /= value;
+        return asImp_();
+    }
+
+protected:
+    //! Provide access to the coordinates of the vector
+    ctype operator[] (unsigned int coordIdx) const
+    { return coordinates_[coordIdx]; }
+
+    //! Provide access to the coordinates of the vector
+    std::array<ctype, wd>& data()
+    { return coordinates_; }
+
+    //! Returns the implementation (static polymorphism)
+    Impl &asImp_() { return *static_cast<Impl*>(this); }
+    //! \copydoc asImp_()
+    const Impl &asImp_() const { return *static_cast<const Impl*>(this); }
+
+private:
+    // storage of the coordinates
+    std::array<ctype, wd> coordinates_;
+};
 
 /*!
  * \brief Vector class implementation.
@@ -254,10 +258,10 @@ class Vector;
  */
 template<class CT>
 class Vector<CT, 1>
-: public Impl::VectorBase< Vector<CT, 1>, CT, 1 >
+: public VectorBase< Vector<CT, 1>, CT, 1 >
 {
     using ThisType = Vector<CT, 1>;
-    using ParentType = Impl::VectorBase<ThisType, CT, 1>;
+    using ParentType = VectorBase<ThisType, CT, 1>;
 
 public:
     //! pull up base class' constructors
@@ -301,10 +305,10 @@ public:
  */
 template<class CT>
 class Vector<CT, 2>
-: public Impl::VectorBase< Vector<CT, 2>, CT, 2 >
+: public VectorBase< Vector<CT, 2>, CT, 2 >
 {
     using ThisType = Vector<CT, 2>;
-    using ParentType = Impl::VectorBase<ThisType, CT, 2>;
+    using ParentType = VectorBase<ThisType, CT, 2>;
 
 public:
     //! pull up base class' constructors
@@ -352,10 +356,10 @@ public:
  */
 template<class CT>
 class Vector<CT, 3>
-: public Impl::VectorBase< Vector<CT, 3>, CT, 3 >
+: public VectorBase< Vector<CT, 3>, CT, 3 >
 {
     using ThisType = Vector<CT, 3>;
-    using ParentType = Impl::VectorBase<ThisType, CT, 3>;
+    using ParentType = VectorBase<ThisType, CT, 3>;
 
 public:
     //! pull up base class' constructors
@@ -403,11 +407,12 @@ public:
 };
 
 /*!
- * \brief \todo TODO Doc me.
- *  \relates Vector
+ * \brief Creates a vector that is
+ *        orthogonal to the provided vector.
+ * \relates Vector
  *
- *  \param v a vector
- *  \returns a vector orthogonal to v
+ * \param v a vector
+ * \returns a vector orthogonal to v
  */
 template<class ctype>
 Vector<ctype, 3> makeOrthogonalVector(const Vector<ctype, 3>& v)

frackit/occ/gputilities.hh

@@ -20,7 +20,7 @@
  * \file
  * \brief Contains utility functionality related
  *        to objects & algorithms related to the
- *        Geometry package in OpenCascade.
+ *        geometric processors package in OpenCascade.
  */
 #ifndef FRACKIT_GP_UTILITIES_HH
 #define FRACKIT_GP_UTILITIES_HH

frackit/sampling/disksampler.hh

@@ -18,12 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
- * \brief Class to randomly generate disks in three-
- *        dimensional space. Generation is done on the
- *        basis of probability distribution functions
- *        provided among construction. The type of
- *        distribution function used in the sampler
- *        class can be defined by passing a traits class.
+ * \brief Class to randomly generate disks in three-dimensional space.
  */
 #ifndef FRACKIT_DISK_SAMPLER_HH
 #define FRACKIT_DISK_SAMPLER_HH
@@ -125,7 +120,10 @@ public:
     {}
 
     /*!
-     * \brief \todo TODO Doc me.
+     * \brief Generate a random disk.
+     * \param pointSampler Point sampler class to
+     *                     randomly sample a point used
+     *                     as the center of the disk.
      */
     template<class PointSampler>
     Disk operator() (PointSampler& pointSampler)

frackit/sampling/geometrysampling.hh

@@ -18,13 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
- * \brief Forward declaration of sampler classes used to
- *        randomly generate geometries. The sampler class
- *        is specialized for different geometries, and the
- *        required probability distribution functions are
- *        injected via corresponding traits classes.
- *        A default traits class should be provided by each
- *        sampler implementation.
+ * \brief Class to randomly generate geometries.
  */
 #ifndef FRACKIT_GEOMETRY_SAMPLING_HH
 #define FRACKIT_GEOMETRY_SAMPLING_HH
@@ -34,7 +28,16 @@ namespace Frackit {
 //! Forward declaration of the default traits
 template<class Geometry> struct DefaultSamplerTraits;
 
-//! Forward declaration of the sampler class
+/*!
+ * \file
+ * \brief Forward declaration of sampler classes used to
+ *        randomly generate geometries. The sampler class
+ *        is specialized for different geometries, and the
+ *        required probability distribution functions are
+ *        injected via corresponding traits classes.
+ *        A default traits class should be provided by each
+ *        sampler implementation.
+ */
 template<class Geometry, class T = DefaultSamplerTraits<Geometry>>
 struct GeometrySampler;
 

frackit/sampling/pointsampling.hh

@@ -18,11 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
- * \brief Class to randomly generate points within geometries.