From f47671f3653d37295c49b94b950e78515b25cc75 Mon Sep 17 00:00:00 2001
From: Jean-Paul Pelteret <jppelteret@gmail.com>
Date: Wed, 24 Oct 2018 14:08:37 +0200
Subject: [PATCH] Improve class documentation

---
 include/deal.II/base/incremental_function.h | 45 ++++++++++++---------
 1 file changed, 27 insertions(+), 18 deletions(-)

diff --git a/include/deal.II/base/incremental_function.h b/include/deal.II/base/incremental_function.h
index 00e30a6eec..a69af70e00 100644
--- a/include/deal.II/base/incremental_function.h
+++ b/include/deal.II/base/incremental_function.h
@@ -28,11 +28,15 @@ class Vector;
 namespace Functions
 {
   /**
-   * This class represents an incremental function. That is, given arbitrary
-   * function <code>func</code>, this class will return
-   * <code>f(t)-f(t-delta)</code>. The decrement is set by the method
-   * set_decrement(). The main application is to transform a given Dirichlet
-   * boundary condition function into the incremental form.
+   * This class represents an incremental function. That is, given an arbitrary
+   * function <code>f</code>, this class will return
+   * <code>f(t) - f(t - delta_t)</code>, where <code>f(t)</code> denotes the
+   * function evaluated at time <code>t</code> and, likewise, <code>f(t -
+   * delta_t)</code> denotes the function evaluated at time <code>t -
+   * delta_t</code>. The decrement <code>delta_t</code> is set by the method
+   * set_decrement(). The main application of this class is to transform a given
+   * Dirichlet boundary condition function into the incremental form, as is
+   * required by some implementations of non-linear solution schemes.
    *
    * @ingroup functions
    * @author Denis Davydov, Jean-Paul Pelteret, 2018
@@ -43,7 +47,7 @@ namespace Functions
   public:
     /**
      * Export the value of the template parameter as a static member constant.
-     * Sometimes useful for some expression template programming.
+     * This is sometimes useful in the context of template programming.
      */
     static const unsigned int dimension = dim;
 
@@ -55,8 +59,9 @@ namespace Functions
     /**
      * Constructor which wraps a given function @p base.
      *
-     * @note this class stores a non-constant reference to @p base
-     * and will call <code>base.set_time()</code> during evaluation.
+     * @note This class stores a non-constant reference to @p base
+     * and will call <code>base.set_time()</code> during evaluation
+     * in order to evaluate the @p base class at any arbitrary time.
      */
     IncrementalFunction(Function<dim, RangeNumberType> &base);
 
@@ -66,10 +71,11 @@ namespace Functions
     virtual ~IncrementalFunction() = default;
 
     /**
-     * Return the value of the function at the given point. Unless there is only
-     * one component (i.e. the function is scalar), you should state the
-     * component you want to have evaluated; it defaults to zero, i.e. the first
-     * component.
+     * Return the value of the function at the given point.
+     *
+     * Unless there is only one component (i.e. the function is scalar), you
+     * should state the component you want to have evaluated. By default, the
+     * value of the first component is computed.
      */
     virtual RangeNumberType
     value(const Point<dim> &p, const unsigned int component = 0) const override;
@@ -77,36 +83,39 @@ namespace Functions
     /**
      * Return all components of a vector-valued function at a given point.
      *
-     * <tt>values</tt> shall have the right size beforehand.
+     * It is required that the @p values vector have the correct size before
+     * this function is called.
      */
     virtual void
     vector_value(const Point<dim> &       p,
                  Vector<RangeNumberType> &values) const override;
 
     /**
-     * Set (positive) time decrement.
+     * Set the time decrement.
+     *
+     * It is expected that this value be positive.
      */
     void
     set_decrement(const time_type delta_t);
 
   private:
     /**
-     * Reference to the function being wrapped.
+     * A reference to the function being wrapped.
      */
     Function<dim, RangeNumberType> &base;
 
     /**
-     * Time decrement.
+     * The time decrement.
      */
     time_type delta_t;
 
     /**
-     * Auxiliary vector to store values
+     * An auxiliary vector to store values.
      */
     mutable Vector<RangeNumberType> values_old;
 
     /**
-     * Thread mutex
+     * Thread mutex for supporting evaluation in multi-threaded contexts.
      */
     mutable Threads::Mutex mutex;
   };
-- 
2.39.5