docu: improve quadrature stuff

also: fix typo on interface implementation file name.

also: move Polynomial into namespace quadrature

Author: torbjoernk

include/pfasst/quadrature.hpp

@@ -1,12 +1,19 @@
+/**
+ * @file pfasst/quadrature.hpp
+ * @since v0.1.0
+ */
 #ifndef _PFASST__QUADRATURE_HPP_
 #define _PFASST__QUADRATURE_HPP_
 
 #include <cmath>
 #include <exception>
-#include <type_traits>
 #include <vector>
+using namespace std;
 
 #include <Eigen/Dense>
+template<typename scalar>
+using Matrix = Eigen::Matrix<scalar, Eigen::Dynamic, Eigen::Dynamic, Eigen::RowMajor>;
+
 #include <boost/math/constants/constants.hpp>
 
 #include "pfasst/config.hpp"
@@ -19,19 +26,29 @@
 #include "pfasst/quadrature/clenshaw_curtis.hpp"
 #include "pfasst/quadrature/uniform.hpp"
 
-template<typename scalar>
-using Matrix = Eigen::Matrix<scalar, Eigen::Dynamic, Eigen::Dynamic, Eigen::RowMajor>;
-
-using namespace std;
 
 namespace pfasst
 {
-
+  /**
+   * functionality related to computing quadrature nodes and weights.
+   *
+   * @note Please note, that all quadrature nodes are in the range \\( [0, 1] \\).
+   */
   namespace quadrature
   {
-
+    /**
+     * instantiates quadrature handler for given number of nodes and type descriptor.
+     *
+     * @tparam precision numerical type of the nodes (e.g. `double`)
+     * @param[in] nnodes number of quadrature nodes
+     * @param[in] qtype type descriptor of the quadrature
+     * @returns instance of pfasst::quadrature::IQuadrature of specified type with desired number
+     *   of nodes
+     * @throws pfasst::ValueError if @p qtype is not a valid quadrature type descriptor
+     */
     template<typename precision = pfasst::time_precision>
-    shared_ptr<IQuadrature<precision>> quadrature_factory(const size_t nnodes, const QuadratureType qtype)
+    shared_ptr<IQuadrature<precision>> quadrature_factory(const size_t nnodes,
+                                                          const QuadratureType qtype)
     {
       if (qtype == QuadratureType::GaussLegendre) {
         return make_shared<GaussLegendre<precision>>(nnodes);
@@ -49,12 +66,28 @@ namespace pfasst
       }
     }
 
+    /**
+     * compute quadrature nodes for given quadrature type descriptor.
+     *
+     * @tparam precision numerical type of the nodes (e.g. `double`)
+     * @param[in] nnodes number of quadrature nodes to compute
+     * @param[in] qtype type descriptor of the quadrature nodes
+     * @returns std::vector of quadrature nodes of given type
+     *
+     * @see pfasst::quadrature::QuadratureType for valid types
+     * @see pfasst::quadrature::quadrature_factory for further details
+     */
     template<typename precision = pfasst::time_precision>
     vector<precision> compute_nodes(size_t nnodes, QuadratureType qtype)
     {
       return quadrature_factory<precision>(nnodes, qtype)->get_nodes();
     }
 
+    /**
+     * @todo write documentation
+     *
+     * @tparam precision numerical type of the interpolation (e.g. `double`)
+     */
     template<typename precision = time_precision>
     Matrix<precision> compute_interp(vector<precision> dst, vector<precision> src)
     {
@@ -84,13 +117,12 @@ namespace pfasst
 
       return mat;
     }
-
   }  // ::pfasst::quadrature
 
+
   namespace config
   {
-    // note: GCC fails with "error: explicit template specialization cannot have a storage class"
-    //       if this template specialization is also declared 'static'; Clang does not care.
+    //! @overload
     template<>
     inline quadrature::QuadratureType get_value(const string& name)
     {
@@ -110,21 +142,18 @@ namespace pfasst
       }
     }
 
-    // note: GCC fails with "error: explicit template specialization cannot have a storage class"
-    //       if this template specialization is also declared 'static'; Clang does not care.
+    //! @overload
     template<>
     inline quadrature::QuadratureType get_value(const string& name,
-                                                        const quadrature::QuadratureType& default_value)
+                                                const quadrature::QuadratureType& default_value)
     {
       if (options::get_instance().get_variables_map().count(name) == 1) {
         return get_value<quadrature::QuadratureType>(name);
       } else {
         return default_value;
       }
     }
-
   } // ::pfasst::config
-
 }  // ::pfasst
 
 #endif  // _PFASST__QUADRATURE_HPP_

include/pfasst/quadrature/clenshaw_curtis.hpp

@@ -1,23 +1,29 @@
+/**
+ * @file pfasst/quadrature/clenshaw_curtis.hpp
+ * @since v0.3.0
+ */
 #ifndef _PFASST__QUADRATURE__CLENSHAW_CURTIS_HPP_
 #define _PFASST__QUADRATURE__CLENSHAW_CURTIS_HPP_
 
 #include <cassert>
 #include <vector>
-
-#include <boost/math/constants/constants.hpp>
+using namespace std;
 
 #include "pfasst/interfaces.hpp"
-#include "pfasst/quadrature/polynomial.hpp"
 #include "pfasst/quadrature/interface.hpp"
 
-using namespace std;
-using namespace boost::math::constants;
-
 
 namespace pfasst
 {
   namespace quadrature
   {
+    /**
+     * quadrature handler for Clenshaw-Curtis quadrature
+     *
+     * @tparam scalar precision of quadrature (i.e. `double`)
+     *
+     * @since v0.3.0
+     */
     template<typename precision = pfasst::time_precision>
     class ClenshawCurtis
       : public IQuadrature<precision>
@@ -30,6 +36,9 @@ namespace pfasst
 
       public:
         //! @{
+        /**
+         * @throws invalid_argument if less than two nodes are requested
+         */
         explicit ClenshawCurtis(const size_t num_nodes);
         ClenshawCurtis() = default;
         virtual ~ClenshawCurtis() = default;

include/pfasst/quadrature/gauss_legendre.hpp

@@ -1,3 +1,7 @@
+/**
+ * @file pfasst/quadrature/gauss_legendre.hpp
+ * @since v0.3.0
+ */
 #ifndef _PFASST__QUADRATURE__GAUSS_LEGENDRE_HPP_
 #define _PFASST__QUADRATURE__GAUSS_LEGENDRE_HPP_
 
@@ -8,6 +12,13 @@ namespace pfasst
 {
   namespace quadrature
   {
+    /**
+     * quadrature handler for Gauss-Legendre quadrature
+     *
+     * @tparam scalar precision of quadrature (i.e. `double`)
+     *
+     * @since v0.3.0
+     */
     template<typename precision = pfasst::time_precision>
     class GaussLegendre
       : public IQuadrature<precision>

include/pfasst/quadrature/gauss_lobatto.hpp

@@ -1,3 +1,7 @@
+/**
+ * @file pfasst/quadrature/gauss_lobatto.hpp
+ * @since v0.3.0
+ */
 #ifndef _PFASST__QUADRATURE__GAUSS_LOBATTO_HPP_
 #define _PFASST__QUADRATURE__GAUSS_LOBATTO_HPP_
 
@@ -8,6 +12,13 @@ namespace pfasst
 {
   namespace quadrature
   {
+    /**
+     * quadrature handler for Gauss-Lobatto quadrature
+     *
+     * @tparam scalar precision of quadrature (i.e. `double`)
+     *
+     * @since v0.3.0
+     */
     template<typename precision = pfasst::time_precision>
     class GaussLobatto
       : public IQuadrature<precision>
@@ -20,6 +31,9 @@ namespace pfasst
 
       public:
         //! @{
+        /**
+         * @throws invalid_argument if less than two nodes are requested
+         */
         explicit GaussLobatto(const size_t num_nodes);
         GaussLobatto() = default;
         virtual ~GaussLobatto() = default;

include/pfasst/quadrature/gauss_radau.hpp

@@ -1,3 +1,7 @@
+/**
+ * @file pfasst/quadrature/gauss_radau.hpp
+ * @since v0.3.0
+ */
 #ifndef _PFASST__QUADRATURE__GAUSS_RADAU_HPP_
 #define _PFASST__QUADRATURE__GAUSS_RADAU_HPP_
 
@@ -8,6 +12,13 @@ namespace pfasst
 {
   namespace quadrature
   {
+    /**
+     * quadrature handler for Gauss-Radau quadrature
+     *
+     * @tparam scalar precision of quadrature (i.e. `double`)
+     *
+     * @since v0.3.0
+     */
     template<typename precision = pfasst::time_precision>
     class GaussRadau
       : public IQuadrature<precision>
@@ -20,6 +31,9 @@ namespace pfasst
 
       public:
         //! @{
+        /**
+         * @throws invalid_argument if less than two nodes are requested
+         */
         explicit GaussRadau(const size_t num_nodes);
         GaussRadau() = default;
         virtual ~GaussRadau() = default;