Merge branch 'issue/documentation' into 'develop'

added documentation of DOFVector and DOFMatrix and improved the documentation of some other classes

See merge request spraetor/dune-amdis!85

src/amdis/ContextGeometry.hpp

@@ -36,6 +36,8 @@ namespace AMDiS
    * Since an intersection has a geometry (and localGeometry) different from the
    * geometry (and localGeometry) of the entity it belongs to, these objects
    * are provided as well.
+   *
+   * \tparam LC  LocalContext, either element or intersection
    **/
   template <class LC>
   struct ContextGeometry
@@ -63,22 +65,25 @@ namespace AMDiS
     {}
 
   public:
-
+    /// Return the bound element (entity of codim 0)
     Element const& element() const
     {
       return *element_;
     }
 
+    /// Return the LocalContext, either the element or an intersection.
     LocalContext const& localContext() const
     {
       return *localContext_;
     }
 
+    /// Return the geometry of the \ref Element
     Geometry const& geometry() const
     {
       return *geometry_;
     }
 
+    /// Return the geometry of the element, or geometryInInside of the intersection
     LocalGeometry const& localGeometry() const
     {
       return localGeometry_impl(IsEntity{});
@@ -87,7 +92,7 @@ namespace AMDiS
 
   public:
 
-    /// Coordinate `p` given in `localGeometry`, transformed to coordinate in `geometry`.
+    /// Coordinate `p` given in `localGeometry`, transformed to coordinate in geometry of the LocalContext.
     template <class Coordinate>
     decltype(auto) local(Coordinate const& p) const
     {

src/amdis/gridfunctions/DOFVectorView.hpp

@@ -35,7 +35,7 @@ namespace AMDiS
      * **Example:**
      * ```
      * auto v = makeDOFVectorView(prob.solutionVector(),0);
-     * v.interpolate([](auto const& x) { return x[0]; });
+     * v.interpolate_noalias([](auto const& x) { return x[0]; });
      * ```
      **/
     template <class Expr>

src/amdis/gridfunctions/DiscreteFunction.hpp

@@ -60,7 +60,7 @@ namespace AMDiS
     /// A LocalFunction representing the derivative of the DOFVector on a bound element
     class GradientLocalFunction;
 
-    /// A LocalFunction representign the value the DOFVector on a bound element
+    /// A LocalFunction representing the value the DOFVector on a bound element
     class LocalFunction;
 
   public:

src/amdis/linearalgebra/DOFMatrixBase.hpp

@@ -11,6 +11,15 @@
 
 namespace AMDiS
 {
+  /**
+   * Basis implementation of DOFMatrix, i.e. a sparse matrix storing all the
+   * assembled Operators indexed with DOF indices. The matrix data is associated
+   * to a row and column global basis.
+   *
+   * \tparam RB  Basis of the matrix rows
+   * \tparam CB  Basis of matrix columns
+   * \tparam Backend  A linear-algebra backend for the matrix storage
+   **/
   template <class RowBasisType, class ColBasisType, class Backend>
   class DOFMatrixBase
   {
@@ -99,7 +108,24 @@ namespace AMDiS
       backend_.insert(flatMultiIndex(row), flatMultiIndex(col), value);
     }
 
-    /// Associate a local operator with this DOFMatrix
+    /// \brief Associate a local operator with this DOFMatrix
+    /**
+     * Stores an operator in a list that gets assembled during a call to \ref assemble().
+     * The operator may be assigned to a specific context, i.e. either an element
+     * operator, an intersection operator, or a boundary operator.
+     * The \p row and \p col tree paths specify the sub-basis for test and trial
+     * functions the operator is applied to.
+     *
+     * \tparam ContextTag  One of \ref tag::element_operator, \ref tag::intersection_operator
+     *                     or \ref tag::boundary_operator indicating where to assemble this operator.
+     * \tparam PreOperator  An pre-operator that can be bound to a gridView, or a valid
+     *                      GridOperator.
+     * \tparam row  A tree-path for the RowBasis
+     * \tparam col  A tree-path for the ColBasis
+     *
+     * [[expects: row is valid tree-path in RowBasis]]
+     * [[expects: col is valid tree-path in ColBasis]]
+     **/
     template <class ContextTag, class Operator,
               class RowTreePath = RootTreePath, class ColTreePath = RootTreePath>
     void addOperator(ContextTag contextTag, Operator const& preOp,

src/amdis/linearalgebra/DOFVectorBase.hpp

@@ -16,7 +16,15 @@
 
 namespace AMDiS
 {
-  /// The basic container that stores a base vector and a corresponding basis
+  /// \brief The basic container that stores a base vector and a corresponding basis
+  /**
+   * Basis implementation of DOFVector, i.e. a vector storing all the
+   * assembled Operators indexed with DOF indices. The vector data is associated
+   * to a global basis.
+   *
+   * \tparam B  Basis of the vector
+   * \tparam Backend  A linear algebra backend implementing the storage and operations.
+   **/
   template <class BasisType, class Backend>
   class DOFVectorBase
       : public DOFVectorInterface

src/amdis/linearalgebra/mtl/DOFMatrix.hpp

@@ -16,8 +16,7 @@
 
 namespace AMDiS
 {
-  /// \brief The basic container that stores a base matrix and a corresponding
-  /// row/column feSpace.
+  /// \brief The basic container that stores a base matrix
   template <class ValueType>
   class MtlMatrix
   {

src/amdis/linearalgebra/mtl/DOFVector.hpp

@@ -9,7 +9,7 @@
 
 namespace AMDiS
 {
-  /// The basic container that stores a base vector and a corresponding basis
+  /// The basic container that stores a base vector data
   template <class ValueType>
   class MtlVector
   {

src/amdis/operations/Composer.hpp

@@ -13,6 +13,19 @@ namespace AMDiS
 {
   namespace Operation
   {
+	    /// \brief Composition of Functors.
+	    /**
+	     * \ingroup operations
+	     * Implement the composition `c:=f(g1,g2,...,gN), where `f` is an N-ary functor
+	     * `gI` are functors of the same arity. The composition is defined as
+	     * ```
+	     * c(a1,a2,...,aM) := f(g1(a1,a2,..,aM), g2(a1,a2,...,aM),...,gN(a1,a2,...,aM))
+	     * ```
+	     *
+	     * **Requirements:**
+	     * - sizeof...(Gs) == N, with N = arity(F)
+	     * - arity(Gs[0]) == arity(Gs[i]) for i = 1,...,N-1
+	     **/
     template <class F, class... Gs>
     struct Composer
     {
@@ -48,7 +61,7 @@ namespace AMDiS
     };
 #endif
 
-    /// Generator function for \ref composer
+    /// Generator function for \ref Composer
     template <class F, class... Gs>
     constexpr auto compose(F&& f, Gs&&... gs)
     {