Get rid of api.rst

ddemidov · Jan 13, 2016 · 463654e · 463654e
1 parent 9ca7b3d
commit 463654e
Show file tree

Hide file tree

Showing 5 changed files with 63 additions and 43 deletions.
diff --git a/amgcl/make_solver.hpp b/amgcl/make_solver.hpp
@@ -37,7 +37,7 @@ THE SOFTWARE.
 
 namespace amgcl {
 
-/// Convenience class that wraps a preconditioner and an iterative solver
+/// Convenience class that bundles together a preconditioner and an iterative solver.
 template <
     class Precond,
     class IterativeSolver
@@ -58,9 +58,13 @@ class make_solver {
 
         typedef typename math::scalar_of<value_type>::type scalar_type;
 
+        /**
+         * Combined parameters of the bundled preconditioner and the iterative
+         * solver.
+         */
         struct params {
-            typename Precond::params         precond;
-            typename IterativeSolver::params solver;
+            typename Precond::params         precond; ///< Preconditioner parameters.
+            typename IterativeSolver::params solver;  ///< Iterative solver parameters.
 
             params() {}
 
@@ -69,8 +73,7 @@ class make_solver {
                   AMGCL_PARAMS_IMPORT_CHILD(p, solver)
             {}
 
-            void get(
-                    boost::property_tree::ptree &p,
+            void get( boost::property_tree::ptree &p,
                     const std::string &path = ""
                     ) const
             {
@@ -79,7 +82,7 @@ class make_solver {
             }
         } prm;
 
-        /// Constructs the preconditioner and creates iterative solver.
+        /** Sets up the preconditioner and creates the iterative solver. */
         template <class Matrix>
         make_solver(
                 const Matrix &A,
@@ -103,19 +106,19 @@ class make_solver {
             S(backend::rows(*A), prm.solver, bprm)
         {}
 
-        /// Solves the linear system for the given system matrix.
         /**
-         * \param A   System matrix.
-         * \param rhs Right-hand side.
-         * \param x   Solution vector.
+         * Computes the solution for the given system matrix \p A and the
+         * right hand side \p rhs.  Returns the number of iterations made and
+         * the achieved residual as a ``boost::tuple``. The solution vector
+         * \p x provides initial approximation in input and holds the computed
+         * solution on output.
          *
          * \rst
-         * The system matrix may differ from the matrix used for the AMG
-         * preconditioner construction. This may be used for the solution of
-         * non-stationary problems with slowly changing coefficients. There is
-         * a strong chance that AMG built for one time step will act as a
-         * reasonably good preconditioner for several subsequent time steps
-         * [DeSh12]_.
+         * The system matrix may differ from the matrix used during
+         * initialization. This may be used for the solution of non-stationary
+         * problems with slowly changing coefficients. There is a strong chance
+         * that a preconditioner built for a time step will act as a reasonably
+         * good preconditioner for several subsequent time steps [DeSh12]_.
          * \endrst
          */
         template <class Matrix, class Vec1, class Vec2>
@@ -132,10 +135,10 @@ class make_solver {
             return S(A, P, rhs, x);
         }
 
-        /// Solves the linear system for the given right-hand side.
-        /**
-         * \param rhs Right-hand side.
-         * \param x   Solution vector.
+        /** Computes the solution for the given right hand side \p rhs.
+         * Returns the number of iterations made and the achieved residual as a
+         * ``boost::tuple``. The solution vector \p x provides initial
+         * approximation in input and holds the computed solution on output.
          */
         template <class Vec1, class Vec2>
         boost::tuple<size_t, scalar_type> operator()(
@@ -150,10 +153,29 @@ class make_solver {
             return S(P, rhs, x);
         }
 
-        /// Acts as a preconditioner.
-        /**
-         * \param rhs Right-hand side.
-         * \param x   Solution vector.
+        /** Acts as a preconditioner. That is, applies the solver to the right
+         * hand side \p rhs to get the solution \p x with zero initial
+         * approximation.  Iterative methods usually use estimated residual for
+         * exit condition.  For some problems the value of the estimated
+         * residual can get too far from the true residual due to round-off
+         * errors.  Nesting iterative solvers in this way may allow to shave
+         * the last bits off the error. The method should not be used directly
+         * but rather allows nesting ``make_solver`` classes as in the
+         * following example:
+         *
+         * \rst
+         * .. code-block:: cpp
+         *
+         *   typedef amgcl::make_solver<
+         *     amgcl::make_solver<
+         *       amgcl::amg<
+         *         Backend, amgcl::coarsening::smoothed_agregation, amgcl::relaxation::spai0
+         *         >,
+         *       amgcl::solver::cg<Backend>
+         *       >,
+         *     amgcl::solver::cg<Backend>
+         *     > NestedSolver;
+         * \endrst
          */
         template <class Vec1, class Vec2>
         void apply(
@@ -169,27 +191,27 @@ class make_solver {
             (*this)(rhs, x);
         }
 
-        /// Reference to the constructed AMG hierarchy.
+        /// Returns reference to the constructed preconditioner.
         const Precond& precond() const {
             return P;
         }
 
-        /// Reference to the iterative solver.
+        /// Returns reference to the constructed iterative solver.
         const IterativeSolver& solver() const {
             return S;
         }
 
-        /// The system matrix in the backend format.
+        /// Returns the system matrix in the backend format.
         typename Precond::matrix const& system_matrix() const {
             return P.system_matrix();
         }
 
-        /// Fills the property tree with the actual parameters used.
+        /// Stores the parameters used during construction into the property tree \p p.
         void get_params(boost::property_tree::ptree &p) const {
             prm.get(p);
         }
 
-        /// Size of the system matrix.
+        /// Returns the size of the system matrix.
         size_t size() const {
             return n;
         }

diff --git a/docs/api.rst b/docs/api.rst
diff --git a/docs/backends.rst b/docs/backends.rst
@@ -43,13 +43,17 @@ Example:
 
     solve(rhs, x);
 
+.. doxygenstruct:: amgcl::backend::builtin
+
 VexCL
 -----
 
 The VexCL backend uses VexCL_ library for accelerating solution on . VexCL is a C++
 vector expression template library for OpenCL/CUDA and is able to utilize
 compute power of the modern GPUs.
 
+.. doxygenstruct:: amgcl::backend::vexcl
+
 .. _Boost: http://www.boost.org/
 .. _VexCL: http://github.com/ddemidov/vexcl
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -30,5 +30,4 @@ Contents:
     runtime
     examples
     bibliography
-    api
     indices
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
@@ -10,7 +10,7 @@ template parameters: the first one specifies a :doc:`preconditioner
 :doc:`backend <backends>`.
 
 Solving Poisson's equation
-------------------------
+--------------------------
 
 Let us consider a simple example of `Poisson's equation`_ in a unit square.
 Here is how the problem may be solved with AMGCL. We will use BiCGStab solver
@@ -141,3 +141,10 @@ of the parameters is not known at compile time:
     Solver solve( boost::tie(n, ptr, col, val), prm );
 
 .. _`boost::property_tree::ptree`: http://www.boost.org/doc/libs/release/doc/html/property_tree.html
+
+
+The ``make_solver`` class
+-------------------------
+
+.. doxygenclass:: amgcl::make_solver
+    :members: