From: Wolfgang Bangerth <bangerth@math.tamu.edu>
Date: Fri, 15 Apr 2016 04:37:36 +0000 (-0500)
Subject: Update documentation of MGLevelObject.
X-Git-Tag: v8.5.0-rc1~1103^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F2509%2Fhead;p=dealii.git

Update documentation of MGLevelObject.
---

diff --git a/include/deal.II/base/mg_level_object.h b/include/deal.II/base/mg_level_object.h
index 3d797e33cc..5d8f97b884 100644
--- a/include/deal.II/base/mg_level_object.h
+++ b/include/deal.II/base/mg_level_object.h
@@ -25,13 +25,20 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * An array with an object for each level.  The purpose of this class is
- * mostly to store objects and allow access by level number, even if the lower
- * levels are not used and therefore have no object at all; this is done by
+ * This class represents an array with one object for each used level of a
+ * multilevel hierarchy, for example for use in the multigrid algorithms.
+ * In contrast to just a generic <code>std::vector</code>, this class allows
+ * to store objects only between some minimal and maximal index (=level),
+ * as one often wants to run a multilevel algorithm only on a subset of
+ * the levels of a mesh (e.g., because the second or third coarsest level is
+ * already small enough that it is cheaper to run a direct solver there,
+ * rather than recurse to even coarser levels). Despite storing objects only
+ * for these "interesting" levels, the class allows indexing simply by
+ * level. Internally, this is of course done by
  * simply shifting the given index by the minimum level we have stored.
  *
- * In most cases, the objects which are stored on each levels, are either
- * matrices or vectors.
+ * In a typical use case for this class, the objects stored on each level
+ * are either matrices or vectors.
  *
  * @ingroup mg
  * @ingroup data
@@ -42,8 +49,23 @@ class MGLevelObject : public Subscriptor
 {
 public:
   /**
-   * Constructor allowing to initialize the number of levels. By default, the
-   * object is created empty.
+   * Constructor. Create a multilevel object with given minimal and
+   * maximal level, and allocate storage for objects on
+   * <code>maxlevel-minlevel+1</code> levels.
+   *
+   * @note Unlike in many other places of the library, the two arguments
+   * here do not denote the first level and last-plus-one level, but indeed
+   * an <i>inclusive</i> range of levels for which to allocate storage
+   * for level objects. Consequently, the defaults for the two arguments
+   * will create an array with one level object, rather than an empty
+   * array.
+   *
+   * @param[in] minlevel The lowest level for which to provision memory
+   *   for level objects.
+   * @param[in] maxlevel The highest level for which to provision memory
+   *   for level objects.
+   *
+   * @pre minlevel <= maxlevel
    */
   MGLevelObject (const unsigned int minlevel = 0,
                  const unsigned int maxlevel = 0);
@@ -54,20 +76,32 @@ public:
   Object &operator[] (const unsigned int level);
 
   /**
-   * Access object on level @p level. Constant version.
+   * Access object on level @p level.
+   *
+   * This function can be called on a @p const object, and
+   * consequently returns a @p const reference.
    */
   const Object &operator[] (const unsigned int level) const;
 
   /**
    * Delete all previous contents of this object and reset its size according
    * to the values of @p new_minlevel and @p new_maxlevel.
+   *
+   * @param[in] new_minlevel The lowest level for which to provision memory
+   *   for level objects.
+   * @param[in] new_maxlevel The highest level for which to provision memory
+   *   for level objects.
+   *
+   * @pre minlevel <= maxlevel
    */
   void resize (const unsigned int new_minlevel,
                const unsigned int new_maxlevel);
 
   /**
-   * Call <tt>operator = (s)</tt> on all objects stored by this object.  This
-   * is particularly useful for e.g. <tt>Object==Vector@<T@></tt>
+   * Call <tt>operator = (s)</tt> on all objects stored by this object.
+   * This clearly requires that the objects stored on each level allow for
+   * this operation. This is, in particular, true for vectors and matrices
+   * if @p d is zero, thereby zeroing out all vector or matrix entries.
    */
   MGLevelObject<Object> &operator = (const double d);
 
@@ -79,12 +113,12 @@ public:
   void clear();
 
   /**
-   * Coarsest level for multigrid.
+   * The coarsest level for which this class stores a level object.
    */
   unsigned int min_level () const;
 
   /**
-   * Finest level for multigrid.
+   * The highest level for which this class stores a level object.
    */
   unsigned int max_level () const;