]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
Reindent comments in parameter_handler.h
authormaier <maier@0785d39b-7218-0410-832d-ea1e28bc413d>
Sat, 13 Jul 2013 12:39:06 +0000 (12:39 +0000)
committermaier <maier@0785d39b-7218-0410-832d-ea1e28bc413d>
Sat, 13 Jul 2013 12:39:06 +0000 (12:39 +0000)
Also 30k get.

git-svn-id: https://svn.dealii.org/trunk@29996 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/include/deal.II/base/parameter_handler.h

index bf9aad7c0ec7d1ca39b22b7caeb090ffc09cb269..09c2435c142541ff749618037c2fa8c4728dd67f 100644 (file)
@@ -55,241 +55,147 @@ namespace Patterns
 {
 
   /**
-   * Base class to declare common
-   * interface. The purpose of this
-   * class is mostly to define the
-   * interface of patterns, and to
-   * force derived classes to have a
-   * <tt>clone</tt> function. It is thus,
-   * in the languages of the "Design
-   * Patterns" book (Gamma et al.), a
-   * "prototype".
+   * Base class to declare common interface. The purpose of this class is
+   * mostly to define the interface of patterns, and to force derived
+   * classes to have a <tt>clone</tt> function. It is thus, in the
+   * languages of the "Design Patterns" book (Gamma et al.), a "prototype".
    */
   class PatternBase
   {
   public:
     /**
-     * Make destructor of this and all
-     * derived classes virtual.
+     * Make destructor of this and all derived classes virtual.
      */
     virtual ~PatternBase ();
 
     /**
-     * Return <tt>true</tt> if the given string
-     * matches the pattern.
+     * Return <tt>true</tt> if the given string matches the pattern.
      */
     virtual bool match (const std::string &test_string) const = 0;
 
     /**
-     * Return a string describing the
-     * pattern.
+     * Return a string describing the pattern.
      */
     virtual std::string description () const = 0;
 
     /**
-     * Return a pointer to an
-     * exact copy of the
-     * object. This is necessary
-     * since we want to store
-     * objects of this type in
-     * containers, were we need
-     * to copy objects without
-     * knowledge of their actual
-     * data type (we only have
-     * pointers to the base
-     * class).
+     * Return a pointer to an exact copy of the object. This is necessary
+     * since we want to store objects of this type in containers, were we
+     * need to copy objects without knowledge of their actual data type (we
+     * only have pointers to the base class).
      *
-     * Ownership of the objects
-     * returned by this function
-     * is passed to the caller of
-     * this function.
+     * Ownership of the objects returned by this function is passed to the
+     * caller of this function.
      */
     virtual PatternBase *clone () const = 0;
 
     /**
-     * Determine an estimate for
-     * the memory consumption (in
-     * bytes) of this object. To
-     * avoid unnecessary
-     * overhead, we do not force
-     * derived classes to provide
-     * this function as a virtual
-     * overloaded one, but rather
-     * try to cast the present
-     * object to one of the known
-     * derived classes and if
-     * that fails then take the
-     * size of this base class
-     * instead and add 32 byte
-     * (this value is arbitrary,
-     * it should account for
-     * virtual function tables,
-     * and some possible data
-     * elements). Since there are
-     * usually not many thousands
-     * of objects of this type
-     * around, and since the
-     * memory_consumption
-     * mechanism is used to find
-     * out where memory in the
-     * range of many megabytes
-     * is, this seems like a
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object. To avoid unnecessary overhead, we do not force derived
+     * classes to provide this function as a virtual overloaded one, but
+     * rather try to cast the present object to one of the known derived
+     * classes and if that fails then take the size of this base class
+     * instead and add 32 byte (this value is arbitrary, it should account
+     * for virtual function tables, and some possible data elements). Since
+     * there are usually not many thousands of objects of this type around,
+     * and since the memory_consumption mechanism is used to find out where
+     * memory in the range of many megabytes is, this seems like a
      * reasonable approximation.
      *
-     * On the other hand, if you
-     * know that your class
-     * deviates from this
-     * assumption significantly,
-     * you can still overload
-     * this function.
+     * On the other hand, if you know that your class deviates from this
+     * assumption significantly, you can still overload this function.
      */
     virtual std::size_t memory_consumption () const;
   };
 
   /**
-  * Returns pointer to the correct
-  * derived class based on description.
+  * Returns pointer to the correct derived class based on description.
   */
   PatternBase *pattern_factory (const std::string &description);
 
   /**
-   * Test for the string being an
-   * integer. If bounds are given
-   * to the constructor, then the
-   * integer given also needs to be
-   * within the interval specified
-   * by these bounds. Note that
-   * unlike common convention in
-   * the C++ standard library, both
-   * bounds of this interval are
-   * inclusive; the reason is that
-   * in practice in most cases, one
-   * needs closed intervals, but
-   * these can only be realized
-   * with inclusive bounds for
-   * non-integer values. We thus
-   * stay consistent by always
-   * using closed intervals.
+   * Test for the string being an integer. If bounds are given to the
+   * constructor, then the integer given also needs to be within the
+   * interval specified by these bounds. Note that unlike common convention
+   * in the C++ standard library, both bounds of this interval are
+   * inclusive; the reason is that in practice in most cases, one needs
+   * closed intervals, but these can only be realized with inclusive bounds
+   * for non-integer values. We thus stay consistent by always using closed
+   * intervals.
    *
-   * If the upper bound given to
-   * the constructor is smaller
-   * than the lower bound, then the
-   * infinite interval is implied,
-   * i.e. every integer is allowed.
+   * If the upper bound given to the constructor is smaller than the lower
+   * bound, then the infinite interval is implied, i.e. every integer is
+   * allowed.
    *
-   * Giving bounds may be useful if
-   * for example a value can only
-   * be positive and less than a
-   * reasonable upper bound (for
-   * example the number of
-   * refinement steps to be
-   * performed), or in many other
-   * cases.
+   * Giving bounds may be useful if for example a value can only be
+   * positive and less than a reasonable upper bound (for example the
+   * number of refinement steps to be performed), or in many other cases.
    */
   class Integer : public PatternBase
   {
   public:
     /**
-     * Minimal integer value. If
-     * the numeric_limits class
-     * is available use this
-     * information to obtain the
-     * extremal values, otherwise
-     * set it so that this class
-     * understands that all values
-     * are allowed.
+     * Minimal integer value. If the numeric_limits class is available use
+     * this information to obtain the extremal values, otherwise set it so
+     * that this class understands that all values are allowed.
      */
     static const int min_int_value;
 
     /**
-     * Maximal integer value. If
-     * the numeric_limits class
-     * is available use this
-     * information to obtain the
-     * extremal values, otherwise
-     * set it so that this class
-     * understands that all values
-     * are allowed.
+     * Maximal integer value. If the numeric_limits class is available use
+     * this information to obtain the extremal values, otherwise set it so
+     * that this class understands that all values are allowed.
      */
     static const int max_int_value;
 
     /**
-     * Constructor. Bounds can be
-     * specified within which a
-     * valid parameter has to
-     * be. If the upper bound is
-     * smaller than the lower
-     * bound, then the infinite
-     * interval is meant. The
-     * default values are chosen
-     * such that no bounds are
-     * enforced on parameters.
+     * Constructor. Bounds can be specified within which a valid parameter
+     * has to be. If the upper bound is smaller than the lower bound, then
+     * the infinite interval is meant. The default values are chosen such
+     * that no bounds are enforced on parameters.
      */
     Integer (const int lower_bound = min_int_value,
              const int upper_bound = max_int_value);
 
     /**
-     * Return <tt>true</tt> if the
-     * string is an integer and
-     * its value is within the
-     * specified range.
+     * Return <tt>true</tt> if the string is an integer and its value is
+     * within the specified range.
      */
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of
-     * the pattern that valid
-     * strings are expected to
-     * match. If bounds were
-     * specified to the
-     * constructor, then include
-     * them into this
-     * description.
+     * Return a description of the pattern that valid strings are expected
+     * to match. If bounds were specified to the constructor, then include
+     * them into this description.
      */
     virtual std::string description () const;
 
     /**
-     * Return a copy of the
-     * present object, which is
-     * newly allocated on the
-     * heap. Ownership of that
-     * object is transferred to
-     * the caller of this
+     * Return a copy of the present object, which is newly allocated on the
+     * heap. Ownership of that object is transferred to the caller of this
      * function.
      */
     virtual PatternBase *clone () const;
 
     /**
-     * Creates new object if the start of
-     * description matches
-     * description_init.  Ownership of that
-     * object is transferred to the caller
-     * of this function.
+     * Creates new object if the start of description matches
+     * description_init.  Ownership of that object is transferred to the
+     * caller of this function.
      */
     static Integer *create (const std::string &description);
 
   private:
     /**
-     * Value of the lower
-     * bound. A number that
-     * satisfies the @ref match
-     * operation of this class
-     * must be equal to this
-     * value or larger, if the
-     * bounds of the interval for
-     * a valid range.
+     * Value of the lower bound. A number that satisfies the @ref match
+     * operation of this class must be equal to this value or larger, if
+     * the bounds of the interval for a valid range.
      */
     const int lower_bound;
 
     /**
-     * Value of the upper
-     * bound. A number that
-     * satisfies the @ref match
-     * operation of this class
-     * must be equal to this
-     * value or less, if the
-     * bounds of the interval for
-     * a valid range.
+     * Value of the upper bound. A number that satisfies the @ref match
+     * operation of this class must be equal to this value or less, if the
+     * bounds of the interval for a valid range.
      */
     const int upper_bound;
 
@@ -300,144 +206,90 @@ namespace Patterns
   };
 
   /**
-   * Test for the string being a
-   * <tt>double</tt>. If bounds are
-   * given to the constructor, then
-   * the integer given also needs
-   * to be within the interval
-   * specified by these
-   * bounds. Note that unlike
-   * common convention in the C++
-   * standard library, both bounds
-   * of this interval are
-   * inclusive; the reason is that
-   * in practice in most cases, one
-   * needs closed intervals, but
-   * these can only be realized
-   * with inclusive bounds for
-   * non-integer values. We thus
-   * stay consistent by always
-   * using closed intervals.
+   * Test for the string being a <tt>double</tt>. If bounds are given to
+   * the constructor, then the integer given also needs to be within the
+   * interval specified by these bounds. Note that unlike common convention
+   * in the C++ standard library, both bounds of this interval are
+   * inclusive; the reason is that in practice in most cases, one needs
+   * closed intervals, but these can only be realized with inclusive bounds
+   * for non-integer values. We thus stay consistent by always using closed
+   * intervals.
    *
-   * If the upper bound given to
-   * the constructor is smaller
-   * than the lower bound, then the
-   * infinite interval is implied,
-   * i.e. every integer is allowed.
+   * If the upper bound given to the constructor is smaller than the lower
+   * bound, then the infinite interval is implied, i.e. every integer is
+   * allowed.
    *
-   * Giving bounds may be useful if
-   * for example a value can only
-   * be positive and less than a
-   * reasonable upper bound (for
-   * example damping parameters are
-   * frequently only reasonable if
-   * between zero and one), or in
-   * many other cases.
+   * Giving bounds may be useful if for example a value can only be
+   * positive and less than a reasonable upper bound (for example damping
+   * parameters are frequently only reasonable if between zero and one), or
+   * in many other cases.
    */
   class Double : public PatternBase
   {
   public:
     /**
-     * Minimal double value. If the
-     * <tt>std::numeric_limits</tt>
-     * class is available use this
-     * information to obtain the
-     * extremal values, otherwise
-     * set it so that this class
-     * understands that all values
-     * are allowed.
+     * Minimal double value. If the <tt>std::numeric_limits</tt> class is
+     * available use this information to obtain the extremal values,
+     * otherwise set it so that this class understands that all values are
+     * allowed.
      */
     static const double min_double_value;
 
     /**
-     * Maximal double value. If the
-     * numeric_limits class is
-     * available use this
-     * information to obtain the
-     * extremal values, otherwise
-     * set it so that this class
-     * understands that all values
-     * are allowed.
+     * Maximal double value. If the numeric_limits class is available use
+     * this information to obtain the extremal values, otherwise set it so
+     * that this class understands that all values are allowed.
      */
     static const double max_double_value;
 
     /**
-     * Constructor. Bounds can be
-     * specified within which a
-     * valid parameter has to
-     * be. If the upper bound is
-     * smaller than the lower
-     * bound, then the infinite
-     * interval is meant. The
-     * default values are chosen
-     * such that no bounds are
-     * enforced on parameters.
+     * Constructor. Bounds can be specified within which a valid parameter
+     * has to be. If the upper bound is smaller than the lower bound, then
+     * the infinite interval is meant. The default values are chosen such
+     * that no bounds are enforced on parameters.
      */
     Double (const double lower_bound = min_double_value,
             const double upper_bound = max_double_value);
 
     /**
-     * Return <tt>true</tt> if the
-     * string is a number and its
-     * value is within the
-     * specified range.
+     * Return <tt>true</tt> if the string is a number and its value is
+     * within the specified range.
      */
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of
-     * the pattern that valid
-     * strings are expected to
-     * match. If bounds were
-     * specified to the
-     * constructor, then include
-     * them into this
-     * description.
+     * Return a description of the pattern that valid strings are expected
+     * to match. If bounds were specified to the constructor, then include
+     * them into this description.
      */
     virtual std::string description () const;
 
     /**
-     * Return a copy of the
-     * present object, which is
-     * newly allocated on the
-     * heap. Ownership of that
-     * object is transferred to
-     * the caller of this
+     * Return a copy of the present object, which is newly allocated on the
+     * heap. Ownership of that object is transferred to the caller of this
      * function.
      */
     virtual PatternBase *clone () const;
 
     /**
-     * Creates new object if the start of
-     * description matches
-     * description_init.  Ownership of that
-     * object is transferred to the caller
-     * of this function.
+     * Creates new object if the start of description matches
+     * description_init.  Ownership of that object is transferred to the
+     * caller of this function.
      */
     static Double *create (const std::string &description);
 
   private:
     /**
-     * Value of the lower
-     * bound. A number that
-     * satisfies the @ref match
-     * operation of this class
-     * must be equal to this
-     * value or larger, if the
-     * bounds of the interval for
-     * a valid range.
+     * Value of the lower bound. A number that satisfies the @ref match
+     * operation of this class must be equal to this value or larger, if
+     * the bounds of the interval for a valid range.
      */
     const double lower_bound;
 
     /**
-     * Value of the upper
-     * bound. A number that
-     * satisfies the @ref match
-     * operation of this class
-     * must be equal to this
-     * value or less, if the
-     * bounds of the interval for
-     * a valid range.
+     * Value of the upper bound. A number that satisfies the @ref match
+     * operation of this class must be equal to this value or less, if the
+     * bounds of the interval for a valid range.
      */
     const double upper_bound;
 
@@ -448,83 +300,59 @@ namespace Patterns
   };
 
   /**
-   * Test for the string being one
-   * of a sequence of values given
-   * like a regular expression. For
-   * example, if the string given
-   * to the constructor is
-   * <tt>"red|blue|black"</tt>, then the
-   * @ref match function returns
-   * <tt>true</tt> exactly if the string
-   * is either "red" or "blue" or
-   * "black". Spaces around the
-   * pipe signs do not matter and
-   * are eliminated.
+   * Test for the string being one of a sequence of values given like a
+   * regular expression. For example, if the string given to the
+   * constructor is <tt>"red|blue|black"</tt>, then the @ref match function
+   * returns <tt>true</tt> exactly if the string is either "red" or "blue"
+   * or "black". Spaces around the pipe signs do not matter and are
+   * eliminated.
    */
   class Selection : public PatternBase
   {
   public:
     /**
-     * Constructor. Take the
-     * given parameter as the
-     * specification of valid
+     * Constructor. Take the given parameter as the specification of valid
      * strings.
      */
     Selection (const std::string &seq);
 
     /**
-     * Return <tt>true</tt> if the
-     * string is an element of
-     * the description list
-     * passed to the constructor.
+     * Return <tt>true</tt> if the string is an element of the description
+     * list passed to the constructor.
      */
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of
-     * the pattern that valid
-     * strings are expected to
-     * match. Here, this is the
-     * list of valid strings
-     * passed to the constructor.
+     * Return a description of the pattern that valid strings are expected
+     * to match. Here, this is the list of valid strings passed to the
+     * constructor.
      */
     virtual std::string description () const;
 
     /**
-     * Return a copy of the
-     * present object, which is
-     * newly allocated on the
-     * heap. Ownership of that
-     * object is transferred to
-     * the caller of this
+     * Return a copy of the present object, which is newly allocated on the
+     * heap. Ownership of that object is transferred to the caller of this
      * function.
      */
     virtual PatternBase *clone () const;
 
     /**
-     * Determine an estimate for
-     * the memory consumption (in
-     * bytes) of this object.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object.
      */
     std::size_t memory_consumption () const;
 
     /**
-     * Creates new object if the start of
-     * description matches
-     * description_init.  Ownership of that
-     * object is transferred to the caller
-     * of this function.
+     * Creates new object if the start of description matches
+     * description_init.  Ownership of that object is transferred to the
+     * caller of this function.
      */
     static Selection *create (const std::string &description);
 
   private:
     /**
-     * List of valid strings as
-     * passed to the
-     * constructor. We don't make
-     * this string constant, as
-     * we process it somewhat in
-     * the constructor.
+     * List of valid strings as passed to the constructor. We don't make
+     * this string constant, as we process it somewhat in the constructor.
      */
     std::string sequence;
 
@@ -536,40 +364,28 @@ namespace Patterns
 
 
   /**
-   * This pattern matches a list of
-   * comma-separated values each of which
-   * have to match a pattern given to the
-   * constructor. With two additional
-   * parameters, the number of elements this
-   * list has to have can be specified. If
-   * none is specified, the list may have
-   * zero or more entries.
+   * This pattern matches a list of comma-separated values each of which
+   * have to match a pattern given to the constructor. With two additional
+   * parameters, the number of elements this list has to have can be
+   * specified. If none is specified, the list may have zero or more
+   * entries.
    */
   class List : public PatternBase
   {
   public:
     /**
-     * Maximal integer value. If
-     * the numeric_limits class
-     * is available use this
-     * information to obtain the
-     * extremal values, otherwise
-     * set it so that this class
-     * understands that all values
-     * are allowed.
+     * Maximal integer value. If the numeric_limits class is available use
+     * this information to obtain the extremal values, otherwise set it so
+     * that this class understands that all values are allowed.
      */
     static const unsigned int max_int_value;
 
     /**
-     * Constructor. Take the
-     * given parameter as the
-     * specification of valid
+     * Constructor. Take the given parameter as the specification of valid
      * elements of the list.
      *
-     * The two other arguments can
-     * be used to denote minimal
-     * and maximal allowable
-     * lengths of the list.
+     * The two other arguments can be used to denote minimal and maximal
+     * allowable lengths of the list.
      */
     List (const PatternBase  &base_pattern,
           const unsigned int  min_elements = 0,
@@ -582,45 +398,34 @@ namespace Patterns
 
     /**
      * Return <tt>true</tt> if the
-     * string is a comma-separated
-     * list of strings each of
-     * which match the pattern
-     * given to the constructor.
+     * string is a comma-separated list of strings each of which match the
+     * pattern given to the constructor.
      */
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of
-     * the pattern that valid
-     * strings are expected to
-     * match.
+     * Return a description of the pattern that valid strings are expected
+     * to match.
      */
     virtual std::string description () const;
 
     /**
-     * Return a copy of the
-     * present object, which is
-     * newly allocated on the
-     * heap. Ownership of that
-     * object is transferred to
-     * the caller of this
+     * Return a copy of the present object, which is newly allocated on the
+     * heap. Ownership of that object is transferred to the caller of this
      * function.
      */
     virtual PatternBase *clone () const;
 
     /**
-     * Creates new object if the start of
-     * description matches
-     * description_init.  Ownership of that
-     * object is transferred to the caller
-     * of this function.
+     * Creates new object if the start of description matches
+     * description_init.  Ownership of that object is transferred to the
+     * caller of this function.
      */
     static List *create (const std::string &description);
 
     /**
-     * Determine an estimate for
-     * the memory consumption (in
-     * bytes) of this object.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object.
      */
     std::size_t memory_consumption () const;
 
@@ -637,21 +442,17 @@ namespace Patterns
     //@}
   private:
     /**
-     * Copy of the pattern that
-     * each element of the list has
-     * to satisfy.
+     * Copy of the pattern that each element of the list has to satisfy.
      */
     PatternBase *pattern;
 
     /**
-     * Minimum number of elements
-     * the list must have.
+     * Minimum number of elements the list must have.
      */
     const unsigned int min_elements;
 
     /**
-     * Maximum number of elements
-     * the list must have.
+     * Maximum number of elements the list must have.
      */
     const unsigned int max_elements;
 
@@ -663,47 +464,33 @@ namespace Patterns
 
 
   /**
-   * This pattern matches a list of
-   * comma-separated values each of which
-   * denotes a pair of key and value. Both key and value
-   * have to match a pattern given to the
-   * constructor. For each entry of the map,
-   * parameters have to be entered in the form
-   * <code>key: value</code>. In other words, a
-   * map is described in the form
+   * This pattern matches a list of comma-separated values each of which
+   * denotes a pair of key and value. Both key and value have to match a
+   * pattern given to the constructor. For each entry of the map,
+   * parameters have to be entered in the form <code>key: value</code>. In
+   * other words, a map is described in the form
    * <code>key1: value1, key2: value2, key3: value3, ...</code>.
    *
-   * With two additional
-   * parameters, the number of elements this
-   * list has to have can be specified. If
-   * none is specified, the map may have
-   * zero or more entries.
+   * With two additional parameters, the number of elements this list has
+   * to have can be specified. If none is specified, the map may have zero
+   * or more entries.
    */
   class Map : public PatternBase
   {
   public:
     /**
-     * Maximal integer value. If
-     * the numeric_limits class
-     * is available use this
-     * information to obtain the
-     * extremal values, otherwise
-     * set it so that this class
-     * understands that all values
-     * are allowed.
+     * Maximal integer value. If the numeric_limits class is available use
+     * this information to obtain the extremal values, otherwise set it so
+     * that this class understands that all values are allowed.
      */
     static const unsigned int max_int_value;
 
     /**
-     * Constructor. Take the
-     * given parameter as the
-     * specification of valid
+     * Constructor. Take the given parameter as the specification of valid
      * elements of the list.
      *
-     * The two other arguments can
-     * be used to denote minimal
-     * and maximal allowable
-     * lengths of the list.
+     * The two other arguments can be used to denote minimal and maximal
+     * allowable lengths of the list.
      */
     Map (const PatternBase  &key_pattern,
          const PatternBase  &value_pattern,
@@ -716,46 +503,34 @@ namespace Patterns
     virtual ~Map ();
 
     /**
-     * Return <tt>true</tt> if the
-     * string is a comma-separated
-     * list of strings each of
-     * which match the pattern
-     * given to the constructor.
+     * Return <tt>true</tt> if the string is a comma-separated list of
+     * strings each of which match the pattern given to the constructor.
      */
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of
-     * the pattern that valid
-     * strings are expected to
-     * match.
+     * Return a description of the pattern that valid strings are expected
+     * to match.
      */
     virtual std::string description () const;
 
     /**
-     * Return a copy of the
-     * present object, which is
-     * newly allocated on the
-     * heap. Ownership of that
-     * object is transferred to
-     * the caller of this
+     * Return a copy of the present object, which is newly allocated on the
+     * heap. Ownership of that object is transferred to the caller of this
      * function.
      */
     virtual PatternBase *clone () const;
 
     /**
-     * Creates new object if the start of
-     * description matches
-     * description_init.  Ownership of that
-     * object is transferred to the caller
-     * of this function.
+     * Creates new object if the start of description matches
+     * description_init.  Ownership of that object is transferred to the
+     * caller of this function.
      */
     static Map *create (const std::string &description);
 
     /**
-     * Determine an estimate for
-     * the memory consumption (in
-     * bytes) of this object.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object.
      */
     std::size_t memory_consumption () const;
 
@@ -772,22 +547,19 @@ namespace Patterns
     //@}
   private:
     /**
-     * Copy of the patterns that
-     * each key and each value of the map has
-     * to satisfy.
+     * Copy of the patterns that each key and each value of the map has to
+     * satisfy.
      */
     PatternBase *key_pattern;
     PatternBase *value_pattern;
 
     /**
-     * Minimum number of elements
-     * the list must have.
+     * Minimum number of elements the list must have.
      */
     const unsigned int min_elements;
 
     /**
-     * Maximum number of elements
-     * the list must have.
+     * Maximum number of elements the list must have.
      */
     const unsigned int max_elements;
 
@@ -799,80 +571,55 @@ namespace Patterns
 
 
   /**
-   * This class is much like the
-   * Selection class, but it
-   * allows the input to be a
-   * comma-separated list of values
-   * which each have to be given in
-   * the constructor
-   * argument. Alternatively, it
-   * could be viewed as a
-   * specialization of the List
-   * class. For example, if the
-   * string to the constructor was
-   * <tt>"ucd|gmv|eps"</tt>, then the
-   * following would be legal input:
-   * <tt>eps</tt>, <tt>gmv</tt>. You may give an
-   * arbitrarily long list of values,
-   * where there may be as many
-   * spaces around commas as you
-   * like.  However, commas are not
-   * allowed inside the values given
+   * This class is much like the Selection class, but it allows the input
+   * to be a comma-separated list of values which each have to be given in
+   * the constructor argument. Alternatively, it could be viewed as a
+   * specialization of the List class. For example, if the string to the
+   * constructor was <tt>"ucd|gmv|eps"</tt>, then the following would be
+   * legal input: <tt>eps</tt>, <tt>gmv</tt>. You may give an arbitrarily
+   * long list of values, where there may be as many spaces around commas
+   * as you like.  However, commas are not allowed inside the values given
    * to the constructor.
    */
   class MultipleSelection : public PatternBase
   {
   public:
     /**
-     * Constructor. Take the
-     * given parameter as the
-     * specification of valid
+     * Constructor. Take the given parameter as the specification of valid
      * strings.
      */
     MultipleSelection (const std::string &seq);
 
     /**
-     * Return <tt>true</tt> if the
-     * string is an element of
-     * the description list
-     * passed to the constructor.
+     * Return <tt>true</tt> if the string is an element of the description
+     * list passed to the constructor.
      */
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of
-     * the pattern that valid
-     * strings are expected to
-     * match. Here, this is the
-     * list of valid strings
-     * passed to the constructor.
+     * Return a description of the pattern that valid strings are expected
+     * to match. Here, this is the list of valid strings passed to the
+     * constructor.
      */
     virtual std::string description () const;
 
     /**
-     * Return a copy of the
-     * present object, which is
-     * newly allocated on the
-     * heap. Ownership of that
-     * object is transferred to
-     * the caller of this
+     * Return a copy of the present object, which is newly allocated on the
+     * heap. Ownership of that object is transferred to the caller of this
      * function.
      */
     virtual PatternBase *clone () const;
 
     /**
-     * Creates new object if the start of
-     * description matches
-     * description_init.  Ownership of that
-     * object is transferred to the caller
-     * of this function.
+     * Creates new object if the start of description matches
+     * description_init.  Ownership of that object is transferred to the
+     * caller of this function.
      */
     static MultipleSelection *create (const std::string &description);
 
     /**
-     * Determine an estimate for
-     * the memory consumption (in
-     * bytes) of this object.
+     * Determine an estimate for the memory consumption (in bytes) of this
+     * object.
      */
     std::size_t memory_consumption () const;
 
@@ -889,12 +636,8 @@ namespace Patterns
     //@}
   private:
     /**
-     * List of valid strings as
-     * passed to the
-     * constructor. We don't make
-     * this string constant, as
-     * we process it somewhat in
-     * the constructor.
+     * List of valid strings as passed to the constructor. We don't make
+     * this string constant, as we process it somewhat in the constructor.
      */
     std::string sequence;
 
@@ -905,10 +648,8 @@ namespace Patterns
   };
 
   /**
-   * Test for the string being
-   * either "true" or "false". This
-   * is mapped to the Selection
-   * class.
+   * Test for the string being either "true" or "false". This is mapped to
+   * the Selection class.
    */
   class Bool : public Selection
   {
@@ -919,30 +660,22 @@ namespace Patterns
     Bool ();
 
     /**
-     * Return a description of
-     * the pattern that valid
-     * strings are expected to
-     * match.
+     * Return a description of the pattern that valid strings are expected
+     * to match.
      */
     virtual std::string description () const;
 
     /**
-     * Return a copy of the
-     * present object, which is
-     * newly allocated on the
-     * heap. Ownership of that
-     * object is transferred to
-     * the caller of this
+     * Return a copy of the present object, which is newly allocated on the
+     * heap. Ownership of that object is transferred to the caller of this
      * function.
      */
     virtual PatternBase *clone () const;
 
     /**
-     * Creates new object if the start of
-     * description matches
-     * description_init.  Ownership of that
-     * object is transferred to the caller
-     * of this function.
+     * Creates new object if the start of description matches
+     * description_init.  Ownership of that object is transferred to the
+     * caller of this function.
      */
     static Bool *create (const std::string &description);
 
@@ -954,54 +687,40 @@ namespace Patterns
   };
 
   /**
-   * Always returns <tt>true</tt> when testing a
-   * string.
+   * Always returns <tt>true</tt> when testing a string.
    */
   class Anything : public PatternBase
   {
   public:
     /**
-     * Constructor. (Allow for at
-     * least one non-virtual
-     * function in this class, as
-     * otherwise sometimes no
-     * virtual table is emitted.)
+     * Constructor. (Allow for at least one non-virtual function in this
+     * class, as otherwise sometimes no virtual table is emitted.)
      */
     Anything ();
 
     /**
-     * Return <tt>true</tt> if the
-     * string matches its
-     * constraints, i.e. always.
+     * Return <tt>true</tt> if the string matches its constraints, i.e.
+     * always.
      */
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of
-     * the pattern that valid
-     * strings are expected to
-     * match. Here, this is the
-     * string <tt>"[Anything]"</tt>.
+     * Return a description of the pattern that valid strings are expected
+     * to match. Here, this is the string <tt>"[Anything]"</tt>.
      */
     virtual std::string description () const;
 
     /**
-     * Return a copy of the
-     * present object, which is
-     * newly allocated on the
-     * heap. Ownership of that
-     * object is transferred to
-     * the caller of this
+     * Return a copy of the present object, which is newly allocated on the
+     * heap. Ownership of that object is transferred to the caller of this
      * function.
      */
     virtual PatternBase *clone () const;
 
     /**
-     * Creates new object if the start of
-     * description matches
-     * description_init.  Ownership of that
-     * object is transferred to the caller
-     * of this function.
+     * Creates new object if the start of description matches
+     * description_init.  Ownership of that object is transferred to the
+     * caller of this function.
      */
     static Anything *create (const std::string &description);
 
@@ -1014,70 +733,51 @@ namespace Patterns
 
 
   /**
-   * A pattern that can be used to indicate
-   * when a parameter is intended to be the
-   * name of a file. By itself, this class
-   * does not check whether the string that
-   * is given in a parameter file actually
-   * corresponds to an existing file (it
-   * could, for example, be the name of a
-   * file to which you want to write
-   * output). Functionally, the class is
-   * therefore equivalent to the Anything
-   * class. However, it allows to specify the
-   * <i>intent</i> of a parameter. The flag
-   * given to the constructor also allows to
-   * specify whether the file is supposed to
-   * be an input or output file.
+   * A pattern that can be used to indicate when a parameter is intended to
+   * be the name of a file. By itself, this class does not check whether
+   * the string that is given in a parameter file actually corresponds to
+   * an existing file (it could, for example, be the name of a file to
+   * which you want to write output). Functionally, the class is therefore
+   * equivalent to the Anything class. However, it allows to specify the
+   * <i>intent</i> of a parameter. The flag given to the constructor also
+   * allows to specify whether the file is supposed to be an input or
+   * output file.
    *
-   * The reason for the existence of this
-   * class is to support graphical user
-   * interfaces for editing parameter
-   * files. These may open a file selection
-   * dialog if the filename is supposed to
-   * represent an input file.
+   * The reason for the existence of this class is to support graphical
+   * user interfaces for editing parameter files. These may open a file
+   * selection dialog if the filename is supposed to represent an input
+   * file.
    */
   class FileName : public PatternBase
   {
   public:
     /**
-     * Files can be used for input
-     * or output. This can be
-     * specified in the constructor
-     * by choosing the flag <tt>type</tt>.
+     * Files can be used for input or output. This can be specified in the
+     * constructor by choosing the flag <tt>type</tt>.
      */
     enum FileType {input = 0, output = 1};
 
     /**
-     * Constructor.  The type of the file
-     * can be specified by choosing the
+     * Constructor.  The type of the file can be specified by choosing the
      * flag.
      */
     FileName (const FileType type = input);
 
     /**
-     * Return <tt>true</tt> if the
-     * string matches its
-     * constraints, i.e. always.
+     * Return <tt>true</tt> if the string matches its constraints, i.e.
+     * always.
      */
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of
-     * the pattern that valid
-     * strings are expected to
-     * match. Here, this is the
-     * string <tt>"[Filename]"</tt>.
+     * Return a description of the pattern that valid strings are expected
+     * to match. Here, this is the string <tt>"[Filename]"</tt>.
      */
     virtual std::string description () const;
 
     /**
-     * Return a copy of the
-     * present object, which is
-     * newly allocated on the
-     * heap. Ownership of that
-     * object is transferred to
-     * the caller of this
+     * Return a copy of the present object, which is newly allocated on the
+     * heap. Ownership of that object is transferred to the caller of this
      * function.
      */
     virtual PatternBase *clone () const;
@@ -1088,11 +788,9 @@ namespace Patterns
     FileType  file_type;
 
     /**
-     * Creates new object if the start of
-     * description matches
-     * description_init.  Ownership of that
-     * object is transferred to the caller
-     * of this function.
+     * Creates new object if the start of description matches
+     * description_init.  Ownership of that object is transferred to the
+     * caller of this function.
      */
     static FileName *create (const std::string &description);
 
@@ -1105,22 +803,16 @@ namespace Patterns
 
 
   /**
-   * A pattern that can be used to indicate
-   * when a parameter is intended to be the
-   * name of a directory. By itself, this
-   * class does not check whether the string
-   * that is given in a parameter file
-   * actually corresponds to an existing
-   * directory. Functionally, the class is
-   * therefore equivalent to the Anything
-   * class. However, it allows to specify the
-   * <i>intent</i> of a parameter.
+   * A pattern that can be used to indicate when a parameter is intended to
+   * be the name of a directory. By itself, this class does not check
+   * whether the string that is given in a parameter file actually
+   * corresponds to an existing directory. Functionally, the class is
+   * therefore equivalent to the Anything class. However, it allows to
+   * specify the <i>intent</i> of a parameter.
    *
-   * The reason for the existence of this
-   * class is to support graphical user
-   * interfaces for editing parameter
-   * files. These may open a file selection
-   * dialog to select or create a directory.
+   * The reason for the existence of this class is to support graphical
+   * user interfaces for editing parameter files. These may open a file
+   * selection dialog to select or create a directory.
    */
   class DirectoryName : public PatternBase
   {
@@ -1131,38 +823,28 @@ namespace Patterns
     DirectoryName ();
 
     /**
-     * Return <tt>true</tt> if the
-     * string matches its
-     * constraints, i.e. always.
+     * Return <tt>true</tt> if the string matches its constraints, i.e.
+     * always.
      */
     virtual bool match (const std::string &test_string) const;
 
     /**
-     * Return a description of
-     * the pattern that valid
-     * strings are expected to
-     * match. Here, this is the
-     * string <tt>"[Filename]"</tt>.
+     * Return a description of the pattern that valid strings are expected
+     * to match. Here, this is the string <tt>"[Filename]"</tt>.
      */
     virtual std::string description () const;
 
     /**
-     * Return a copy of the
-     * present object, which is
-     * newly allocated on the
-     * heap. Ownership of that
-     * object is transferred to
-     * the caller of this
+     * Return a copy of the present object, which is newly allocated on the
+     * heap. Ownership of that object is transferred to the caller of this
      * function.
      */
     virtual PatternBase *clone () const;
 
     /**
-     * Creates new object if the start of
-     * description matches
-     * description_init.  Ownership of that
-     * object is transferred to the caller
-     * of this function.
+     * Creates new object if the start of description matches
+     * description_init.  Ownership of that object is transferred to the
+     * caller of this function.
      */
     static DirectoryName *create (const std::string &description);
 
@@ -1176,10 +858,11 @@ namespace Patterns
 
 
 /**
- *   The ParameterHandler class provides a standard interface to an input file
- *   which provides at run-time for program parameters such as time step
- *   sizes, geometries, right hand sides etc. The input for the program is
- *   given in files, streams or strings in memory using text like
+ *   The ParameterHandler class provides a standard interface to an input
+ *   file which provides at run-time for program parameters such as time
+ *   step sizes, geometries, right hand sides etc. The input for the
+ *   program is given in files, streams or strings in memory using text
+ *   like
  *   @code
  *     set Time step size = 0.3
  *     set Geometry       = [0,1]x[0,3]
@@ -1187,16 +870,15 @@ namespace Patterns
  *   Input may be sorted into subsection trees in order to give the input a
  *   logical structure.
  *
- *   The ParameterHandler class is discussed in detail in the @ref
- *   step_19 "step-19" example program, and is used in more realistic
- *   situations in step-29, step-33
- *   and step-34.
+ *   The ParameterHandler class is discussed in detail in the @ref step_19
+ *   "step-19" example program, and is used in more realistic situations in
+ *   step-29, step-33 and step-34.
  *
  *   <h3>Declaring entries</h3>
  *
- *   In order to use the facilities of a ParameterHandler object, one first has
- *   to make known the different entries the input file may or may not contain. This
- *   is done in the following way:
+ *   In order to use the facilities of a ParameterHandler object, one first
+ *   has to make known the different entries the input file may or may not
+ *   contain. This is done in the following way:
  *
  *   @code
  *     ...
@@ -1210,26 +892,24 @@ namespace Patterns
  *                       Patterns::Anything());
  *     ...
  *   @endcode
- *   Each entry is declared using the function declare_entry(). The
- *   first parameter is the name of the entry (in short: the
- *   entry). The second is the default answer to be taken in case the
- *   entry is not specified in the input file. The third parameter is
- *   a regular expression which the input (and the default answer) has
- *   to match.  Several such regular expressions are defined in
- *   Patterns. This parameter can be omitted, in which case it
- *   will default to Patterns::Anything, i.e. a pattern that
+ *   Each entry is declared using the function declare_entry(). The first
+ *   parameter is the name of the entry (in short: the entry). The second
+ *   is the default answer to be taken in case the entry is not specified
+ *   in the input file. The third parameter is a regular expression which
+ *   the input (and the default answer) has to match.  Several such regular
+ *   expressions are defined in Patterns. This parameter can be omitted, in
+ *   which case it will default to Patterns::Anything, i.e. a pattern that
  *   matches every input string. The fourth parameter can be used to
  *   document the intent or expected format of an entry; its value is
- *   printed as a comment when writing all entries of a
- *   ParameterHandler object using the print_parameters()
- *   function to allow for easier understanding of a parameter
- *   file. It can be omitted as well, in which case no such
- *   documentation will be printed.
- *
- *   Entries may be located in subsections which form a kind of input tree. For example
- *   input parameters for linear solver routines should be classified in a subsection
- *   named <tt>Linear solver</tt> or any other suitable name. This is accomplished in the
- *   following way:
+ *   printed as a comment when writing all entries of a ParameterHandler
+ *   object using the print_parameters() function to allow for easier
+ *   understanding of a parameter file. It can be omitted as well, in which
+ *   case no such documentation will be printed.
+ *
+ *   Entries may be located in subsections which form a kind of input tree.
+ *   For example input parameters for linear solver routines should be
+ *   classified in a subsection named <tt>Linear solver</tt> or any other
+ *   suitable name. This is accomplished in the following way:
  *   @code
  *     ...
  *       LinEq eq;
@@ -1252,9 +932,10 @@ namespace Patterns
  *     }
  *   @endcode
  *
- *   Subsections may be nested. For example a nonlinear solver may have a linear solver
- *   as member object. Then the function call tree would be something like (if the class
- *   <tt>NonLinEq</tt> has a member variables <tt>eq</tt> of type <tt>LinEq</tt>):
+ *   Subsections may be nested. For example a nonlinear solver may have a
+ *   linear solver as member object. Then the function call tree would be
+ *   something like (if the class <tt>NonLinEq</tt> has a member variables
+ *   <tt>eq</tt> of type <tt>LinEq</tt>):
  *   @code
  *     void NonLinEq::declare_parameters (ParameterHandler &prm) {
  *       prm.enter_subsection ("Nonlinear solver");
@@ -1268,15 +949,15 @@ namespace Patterns
  *     }
  *   @endcode
  *
- *   For class member functions which declare the different entries we propose
- *   to use the common name <tt>declare_parameters</tt>. In normal cases this
- *   method can be <tt>static</tt> since the entries will not depend on any
- *   previous knowledge. Classes for which entries should logically be grouped
- *   into subsections should declare these subsections themselves. If a class
- *   has two or more member variables of the same type both of which should
- *   have their own parameters, this parent class' method
- *   <tt>declare_parameters</tt> is responsible to group them into different
- *   subsections:
+ *   For class member functions which declare the different entries we
+ *   propose to use the common name <tt>declare_parameters</tt>. In normal
+ *   cases this method can be <tt>static</tt> since the entries will not
+ *   depend on any previous knowledge. Classes for which entries should
+ *   logically be grouped into subsections should declare these subsections
+ *   themselves. If a class has two or more member variables of the same
+ *   type both of which should have their own parameters, this parent
+ *   class' method <tt>declare_parameters</tt> is responsible to group them
+ *   into different subsections:
  *   @code
  *     void NonLinEq::declare_parameters (ParameterHandler &prm) {
  *       prm.enter_subsection ("Nonlinear solver");
@@ -1313,27 +994,30 @@ namespace Patterns
  *     end
  *     ...                       # other stuff
  *   @endcode
- *   The words <tt>subsection</tt>, <tt>set</tt> and <tt>end</tt> may be either written in lowercase or uppercase
- *   letters. Leading and trailing whitespace is removed, multiple whitespace is condensed into
- *   only one. Since the latter applies also to the name of an entry, an entry name will not
- *   be recognized if in the declaration multiple whitespace is used.
+ *   The words <tt>subsection</tt>, <tt>set</tt> and <tt>end</tt> may be
+ *   either written in lowercase or uppercase letters. Leading and trailing
+ *   whitespace is removed, multiple whitespace is condensed into only one.
+ *   Since the latter applies also to the name of an entry, an entry name
+ *   will not be recognized if in the declaration multiple whitespace is
+ *   used.
  *
- *   In entry names and values the following characters are not allowed: <tt>\#</tt>, <tt>{</tt>,
- *   <tt>}</tt>, <tt>|</tt>. Their use is reserved for the MultipleParameterLoop class.
+ *   In entry names and values the following characters are not allowed:
+ *   <tt>\#</tt>, <tt>{</tt>, <tt>}</tt>, <tt>|</tt>. Their use is reserved
+ *   for the MultipleParameterLoop class.
  *
  *   Comments starting with \# are skipped.
  *
- *   We propose to use the following
- *   scheme to name entries: start the first word with a capital letter and use lowercase
- *   letters further on. The same applies to the possible entry values to the right of the
+ *   We propose to use the following scheme to name entries: start the
+ *   first word with a capital letter and use lowercase letters further on.
+ *   The same applies to the possible entry values to the right of the
  *   <tt>=</tt> sign.
  *
  *
  *   <h3>Reading data from input sources</h3>
  *
- *   In order to read input you can use three possibilities: reading from an
- *   <tt>std::istream</tt> object, reading from a file of which the name is
- *   given and reading from a string in memory in which the lines are
+ *   In order to read input you can use three possibilities: reading from
+ *   an <tt>std::istream</tt> object, reading from a file of which the name
+ *   is given and reading from a string in memory in which the lines are
  *   separated by <tt>@\n</tt> characters. These possibilities are used as
  *   follows:
  *   @code
@@ -1349,40 +1033,42 @@ namespace Patterns
  *     prm.read_input_from_string (in);
  *     ...
  *   @endcode
- *   You can use several sources of input successively. Entries which are changed more than
- *   once will be overwritten every time they are used.
+ *   You can use several sources of input successively. Entries which are
+ *   changed more than once will be overwritten every time they are used.
  *
  *   You should not try to declare entries using declare_entry() and
  *   enter_subsection() with as yet unknown subsection names after
  *   using read_input(). The results in this case are unspecified.
  *
- *   If an error occurs upon reading the input, error messages are written to
- *   <tt>std::cerr</tt> and the reader function returns with a return value of
- *   <code>false</code>. This is opposed to almost all other functions in
- *   deal.II, which would normally throw an exception if an error occurs; this
- *   difference in behavior is a relic of the fact that this class predates
- *   deal.II and had previously been written for a different project.
+ *   If an error occurs upon reading the input, error messages are written
+ *   to <tt>std::cerr</tt> and the reader function returns with a return
+ *   value of <code>false</code>. This is opposed to almost all other
+ *   functions in deal.II, which would normally throw an exception if an
+ *   error occurs; this difference in behavior is a relic of the fact that
+ *   this class predates deal.II and had previously been written for a
+ *   different project.
  *
  *
  *   <h3>Using the %ParameterHandler Graphical User Interface</h3>
  *
  *   An alternative to using the hand-written input files shown above is to
- *   use the graphical user interface (GUI) that accompanies this class. For
- *   this, you first need to write a description of all the parameters, their
- *   default values, patterns and documentation strings into a file in a
- *   format that the GUI can understand; this is done using the
- *   ParameterHandler::print_parameters() function with ParameterHandler::XML
- *   as second argument, as discussed in more detail below in the
- *   <i>Representation of Parameters</i> section. This file can then be loaded
- *   using the executable for the GUI, which should be located in
- *   <code>lib/bin/dealii_parameter_gui</code> of your deal.II installation,
- *   assuming that you have a sufficiently recent version of the <a
- *   href="http://qt.nokia.com/">Qt toolkit</a> installed.
+ *   use the graphical user interface (GUI) that accompanies this class.
+ *   For this, you first need to write a description of all the parameters,
+ *   their default values, patterns and documentation strings into a file
+ *   in a format that the GUI can understand; this is done using the
+ *   ParameterHandler::print_parameters() function with
+ *   ParameterHandler::XML as second argument, as discussed in more detail
+ *   below in the <i>Representation of Parameters</i> section. This file
+ *   can then be loaded using the executable for the GUI, which should be
+ *   located in <code>lib/bin/dealii_parameter_gui</code> of your deal.II
+ *   installation, assuming that you have a sufficiently recent version of
+ *   the <a href="http://qt.nokia.com/">Qt toolkit</a> installed.
  *
  *   Once loaded, the GUI displays subsections and individual parameters in
  *   tree form (see also the discussion in the <i>Representation of
- *   Parameters</i> section below). Here is a screen shot with some
- *   sub-sections expanded and one parameter selected for editing:
+ *   Parameters</i> section below). Here is a screen shot
+ *   with some sub-sections expanded and one parameter selected for
+ *   editing:
  *
  *   @image html parameter_gui.png "Parameter GUI"
  *
@@ -1403,54 +1089,61 @@ namespace Patterns
  *       prm.leave_subsection ();
  *     }
  *   @endcode
- *   get() returns the value of the given entry. If the entry was not specified in the input
- *   source(s), the default value is returned. You have to enter and leave subsections
- *   exactly as you did when declaring subsection. You may chose the order in which to
- *   transverse the subsection tree.
- *
- *   It is guaranteed that only entries matching the given regular expression are returned,
- *   i.e. an input entry value which does not match the regular expression is not stored.
- *
- *   You can use get() to retrieve the parameter in text form, get_integer() to get an integer
- *   or get_double() to get a double. You can also use get_bool().
- *   It will cause an internal error if the string could not be
- *   converted to an integer, double or a bool. This should, though, not
- *   happen if you correctly specified the regular expression for this entry; you should not
- *   try to get out an integer or a double from an entry for which no according regular
- *   expression was set. The internal error is raised through the Assert() macro family
- *   which only works in debug mode.
+ *   get() returns the value of the given entry. If the entry was not
+ *   specified in the input source(s), the default value is returned. You
+ *   have to enter and leave subsections exactly as you did when declaring
+ *   subsection. You may chose the order in which to transverse the
+ *   subsection tree.
+ *
+ *   It is guaranteed that only entries matching the given regular
+ *   expression are returned, i.e. an input entry value which does not
+ *   match the regular expression is not stored.
+ *
+ *   You can use get() to retrieve the parameter in text form,
+ *   get_integer() to get an integer or get_double() to get a double. You
+ *   can also use get_bool(). It will cause an internal error if the string
+ *   could not be converted to an integer, double or a bool. This should,
+ *   though, not happen if you correctly specified the regular expression
+ *   for this entry; you should not try to get out an integer or a double
+ *   from an entry for which no according regular expression was set. The
+ *   internal error is raised through the Assert() macro family which only
+ *   works in debug mode.
  *
  *   If you want to print out all user selectable features, use the
- *   print_parameters() function. It is generally a good idea to print all parameters
- *   at the beginning of a log file, since this way input and output are together in
- *   one file which makes matching at a later time easier. Additionally, the function
- *   also print those entries which have not been modified in the input file und are
- *   thus set to default values; since default values may change in the process of
- *   program development, you cannot know the values of parameters not specified in the
- *   input file.
+ *   print_parameters() function. It is generally a good idea to print all
+ *   parameters at the beginning of a log file, since this way input and
+ *   output are together in one file which makes matching at a later time
+ *   easier. Additionally, the function also print those entries which have
+ *   not been modified in the input file und are thus set to default
+ *   values; since default values may change in the process of program
+ *   development, you cannot know the values of parameters not specified in
+ *   the input file.
  *
  *
  *   <h3>Style guide for data retrieval</h3>
  *
- *   We propose that every class which gets data out of a
- *   ParameterHandler object provides a function named
- *   <tt>get_parameters</tt>. This should be declared
- *   <tt>virtual</tt>. <tt>get_parameters</tt> functions in derived classes
- *   should call the <tt>BaseClass::get_parameters</tt> function.
+ *   We propose that every class which gets data out of a ParameterHandler
+ *   object provides a function named <tt>get_parameters</tt>. This should
+ *   be declared <tt>virtual</tt>. <tt>get_parameters</tt> functions in
+ *   derived classes should call the <tt>BaseClass::get_parameters</tt>
+ *   function.
  *
  *
  *   <h3>Experience with large parameter lists</h3>
  *
- *   Experience has shown that in programs defining larger numbers of parameters (more than,
- *   say, fifty) it is advantageous to define an additional class holding these parameters.
- *   This class is more like a C-style structure, having a large number of variables,
- *   usually public. It then has at least two functions, which declare and parse the
- *   parameters. In the main program, the main class has an object of this parameter class
- *   and delegates declaration and parsing of parameters to this object.
+ *   Experience has shown that in programs defining larger numbers of
+ *   parameters (more than, say, fifty) it is advantageous to define an
+ *   additional class holding these parameters. This class is more like a
+ *   C-style structure, having a large number of variables, usually public.
+ *   It then has at least two functions, which declare and parse the
+ *   parameters. In the main program, the main class has an object of this
+ *   parameter class and delegates declaration and parsing of parameters to
+ *   this object.
  *
- *   The advantage of this approach is that you can keep out the technical details
- *   (declaration and parsing) out of the main class and additionally don't clutter
- *   up your main class with dozens or more variables denoting the parameters.
+ *   The advantage of this approach is that you can keep out the technical
+ *   details (declaration and parsing) out of the main class and
+ *   additionally don't clutter up your main class with dozens or more
+ *   variables denoting the parameters.
  *
  *
  *
@@ -1701,9 +1394,9 @@ namespace Patterns
  *     prm.leave_subsection ();
  *   @endcode
  *
- *   We can think of the parameters so arranged as a file system in which every
- *   parameter is a directory. The name of this directory is the name of the
- *   parameter, and in this directory lie files that describe the
+ *   We can think of the parameters so arranged as a file system in which
+ *   every parameter is a directory. The name of this directory is the name
+ *   of the parameter, and in this directory lie files that describe the
  *   parameter. These files are:
  *   - <code>value</code>: The content of this file is the current value of this
  *     parameter; initially, the content of the file equals the default value of
@@ -1720,13 +1413,13 @@ namespace Patterns
  *   With the exception of the <code>value</code> file, the contents of files
  *   are never changed after declaration of a parameter.
  *
- *   Alternatively, a directory in this file system may not have a file called
- *   <code>value</code> in it. In that case, the directory represents a
- *   subsection as declared above, and the directory's name will correspond to
- *   the name of the subsection. It will then have no files in it at all, but
- *   it may have further directories in it: some of these directories will be
- *   parameters (indicates by the presence of files) or further nested
- *   subsections.
+ *   Alternatively, a directory in this file system may not have a file
+ *   called <code>value</code> in it. In that case, the directory
+ *   represents a subsection as declared above, and the directory's name
+ *   will correspond to the name of the subsection. It will then have no
+ *   files in it at all, but it may have further directories in it: some of
+ *   these directories will be parameters (indicates by the presence of
+ *   files) or further nested subsections.
  *
  *   Given this explanation, the code above will lead to a hierarchical
  *   representation of data that looks like this (the content of files is
@@ -1791,74 +1484,57 @@ class ParameterHandler : public Subscriptor
 {
 private:
   /**
-   * Inhibit automatic
-   * CopyConstructor.
+   * Inhibit automatic CopyConstructor.
    */
   ParameterHandler (const ParameterHandler &);
 
   /**
-   * Inhibit automatic
-   * assignment operator.
+   * Inhibit automatic assignment operator.
    */
   ParameterHandler &operator= (const ParameterHandler &);
 
 public:
   /**
-   * List of possible output
-   * formats.
+   * List of possible output formats.
    *
-   * The formats down the list with
-   * prefix <em>Short</em> and bit
-   * 6 and 7 set reproduce the old
-   * behavior of not writing
-   * comments or original values to
-   * the files.
+   * The formats down the list with prefix <em>Short</em> and bit 6 and 7
+   * set reproduce the old behavior of not writing comments or original
+   * values to the files.
    */
   enum OutputStyle
   {
     /**
-     * Write human readable
-     * output suitable to be
-     * read by ParameterHandler
+     * Write human readable output suitable to be read by ParameterHandler
      * again.
      */
     Text = 1,
     /**
-     * Write parameters as a
-     * LaTeX table.
+     * Write parameters as a LaTeX table.
      */
     LaTeX = 2,
     /**
-     * Write out declared parameters
-     * with description and possible
-     * values.
+     * Write out declared parameters with description and possible values.
      */
     Description = 3,
 
     /**
-     * Write out everything as
-     * an <a href="http://en.wikipedia.org/wiki/XML">XML</a>
-     * file.
+     * Write out everything as an <a
+     * href="http://en.wikipedia.org/wiki/XML">XML</a> file.
      *
-     * See the general
-     * documentation of this
-     * class for an example of
+     * See the general documentation of this class for an example of
      * output.
      */
     XML = 4,
 
     /**
-     * Write out everything as
-     * a <a href="http://en.wikipedia.org/wiki/JSON">JSON</a>
-     * file.
+     * Write out everything as a <a
+     * href="http://en.wikipedia.org/wiki/JSON">JSON</a> file.
      */
     JSON = 5,
 
     /**
-     * Write input for
-     * ParameterHandler without
-     * comments or changed
-     * default values.
+     * Write input for ParameterHandler without comments or changed default
+     * values.
      */
     ShortText = 193
   };
@@ -1871,73 +1547,51 @@ public:
   ParameterHandler ();
 
   /**
-   * Destructor. Declare this only
-   * to have a virtual destructor,
-   * which is safer as we have
-   * virtual functions.  It
-   * actually does nothing
+   * Destructor. Declare this only to have a virtual destructor, which is
+   * safer as we have virtual functions.  It actually does nothing
    * spectacular.
    */
   virtual ~ParameterHandler ();
 
   /**
-   * Read input from a stream until
-   * stream returns <tt>eof</tt>
-   * condition or error.
+   * Read input from a stream until stream returns <tt>eof</tt> condition
+   * or error.
    *
-   * Return whether the read was
-   * successful.
+   * Return whether the read was successful.
    */
   virtual bool read_input (std::istream &input);
 
   /**
-   * Read input from a file the
-   * name of which is given. The
-   * PathSearch class "PARAMETERS"
-   * is used to find the file.
+   * Read input from a file the name of which is given. The PathSearch
+   * class "PARAMETERS" is used to find the file.
    *
-   * Return whether the read was
-   * successful.
+   * Return whether the read was successful.
    *
-   * Unless <tt>optional</tt> is
-   * <tt>true</tt>, this function
-   * will automatically generate
-   * the requested file with
-   * default values if the file did
-   * not exist. This file will not
-   * contain additional comments if
-   * <tt>write_stripped_file</tt>
-   * is <tt>true</tt>.
+   * Unless <tt>optional</tt> is <tt>true</tt>, this function will
+   * automatically generate the requested file with default values if the
+   * file did not exist. This file will not contain additional comments if
+   * <tt>write_stripped_file</tt> is <tt>true</tt>.
    */
   virtual bool read_input (const std::string &filename,
                            const bool optional = false,
                            const bool write_stripped_file = false);
 
   /**
-   * Read input from a string in
-   * memory. The lines in memory
-   * have to be separated by <tt>@\n</tt>
-   * characters.
+   * Read input from a string in memory. The lines in memory have to be
+   * separated by <tt>@\n</tt> characters.
    *
-   * Return whether the read was
-   * successful.
+   * Return whether the read was successful.
    */
   virtual bool read_input_from_string (const char *s);
 
   /**
-   * Read a parameter file in XML
-   * format. This could be from a file
-   * originally written by the
-   * print_parameters() function using the
-   * XML output style and then modified by
-   * hand as necessary; or from a file
-   * written using this method and then
-   * modified by the graphical parameter
-   * GUI (see the general documentation of
-   * this class).
+   * Read a parameter file in XML format. This could be from a file
+   * originally written by the print_parameters() function using the XML
+   * output style and then modified by hand as necessary; or from a file
+   * written using this method and then modified by the graphical parameter
+   * GUI (see the general documentation of this class).
    *
-   * Return whether the read was
-   * successful.
+   * Return whether the read was successful.
    */
   virtual bool read_input_from_xml (std::istream &input);
 
@@ -1948,30 +1602,17 @@ public:
 
 
   /**
-   * Declare a new entry with name
-   * <tt>entry</tt>, default and for
-   * which any input has to match
-   * the <tt>pattern</tt> (default: any
-   * pattern).
+   * Declare a new entry with name <tt>entry</tt>, default and for which
+   * any input has to match the <tt>pattern</tt> (default: any pattern).
    *
-   * The last parameter defaulting
-   * to an empty string is used to
-   * add a documenting text to each
-   * entry which will be printed as
-   * a comment when this class is
-   * asked to write out all
-   * declarations to a stream using
-   * the print_parameters()
-   * function.
+   * The last parameter defaulting to an empty string is used to add a
+   * documenting text to each entry which will be printed as a comment when
+   * this class is asked to write out all declarations to a stream using
+   * the print_parameters() function.
    *
-   * The function generates an
-   * exception if the default value
-   * doesn't match the given
-   * pattern. An entry can be
-   * declared more than once
-   * without generating an error,
-   * for example to override an
-   * earlier default value.
+   * The function generates an exception if the default value doesn't match
+   * the given pattern. An entry can be declared more than once without
+   * generating an error, for example to override an earlier default value.
    */
   void declare_entry (const std::string           &entry,
                       const std::string           &default_value,
@@ -1979,221 +1620,146 @@ public:
                       const std::string           &documentation = std::string());
 
   /**
-   * Enter a subsection; if not yet
-   * existent, declare it.
+   * Enter a subsection; if not yet existent, declare it.
    */
   void enter_subsection (const std::string &subsection);
 
   /**
-   * Leave present subsection.
-   * Return <tt>false</tt> if there is
-   * no subsection to leave; <tt>true</tt>
-   * otherwise.
+   * Leave present subsection. Return <tt>false</tt> if there is no
+   * subsection to leave; <tt>true</tt> otherwise.
    */
   bool leave_subsection ();
 
   /**
-   * Return value of entry
-   * <tt>entry_string</tt>.  If the
-   * entry was changed, then the
-   * changed value is returned,
-   * otherwise the default
-   * value. If the value of an
-   * undeclared entry is required,
-   * an exception will be thrown.
+   * Return value of entry <tt>entry_string</tt>.  If the entry was
+   * changed, then the changed value is returned, otherwise the default
+   * value. If the value of an undeclared entry is required, an exception
+   * will be thrown.
    */
   std::string get (const std::string &entry_string) const;
 
   /**
-   * Return value of entry
-   * <tt>entry_string</tt> as <tt>long
-   * int</tt>. (A long int is chosen so
-   * that even very large unsigned values
-   * can be returned by this function).
+   * Return value of entry <tt>entry_string</tt> as <tt>long int</tt>. (A
+   * long int is chosen so that even very large unsigned values can be
+   * returned by this function).
    */
   long int       get_integer (const std::string &entry_string) const;
 
   /**
-   * Return value of entry
-   * <tt>entry_name</tt> as
-   * <tt>double</tt>.
+   * Return value of entry <tt>entry_name</tt> as <tt>double</tt>.
    */
   double         get_double (const std::string &entry_name) const;
 
   /**
-   * Return value of entry
-   * <tt>entry_name</tt> as <tt>bool</tt>.
-   * The entry may be "true" or "yes"
-   * for <tt>true</tt>, "false" or
-   * "no" for <tt>false</tt> respectively.
+   * Return value of entry <tt>entry_name</tt> as <tt>bool</tt>. The entry
+   * may be "true" or "yes" for <tt>true</tt>, "false" or "no" for
+   * <tt>false</tt> respectively.
    */
   bool           get_bool (const std::string &entry_name) const;
 
   /**
-   * Change the value presently stored for
-   * <tt>entry_name</tt> to the one given
-   * in the second argument.
+   * Change the value presently stored for <tt>entry_name</tt> to the one
+   * given in the second argument.
    *
-   * The parameter must already exist in
-   * the present subsection.
+   * The parameter must already exist in the present subsection.
    *
-   * The function throws an
-   * exception of type
-   * ExcValueDoesNotMatchPattern
-   * if the new value does not
-   * conform to the pattern for
-   * this entry.
+   * The function throws an exception of type ExcValueDoesNotMatchPattern
+   * if the new value does not conform to the pattern for this entry.
    */
   void           set (const std::string &entry_name,
                       const std::string &new_value);
 
   /**
-   * Same as above, but an overload where
-   * the second argument is a character
-   * pointer. This is necessary, since
-   * otherwise the call to
-   * <tt>set("abc","def")</code> will be
-   * mapped to the function taking one
-   * string and a bool as arguments, which
-   * is certainly not what is most often
-   * intended.
+   * Same as above, but an overload where the second argument is a
+   * character pointer. This is necessary, since otherwise the call to
+   * <tt>set("abc","def")</code> will be mapped to the function taking one
+   * string and a bool as arguments, which is certainly not what is most
+   * often intended.
    *
-   * The function throws an
-   * exception of type
-   * ExcValueDoesNotMatchPattern
-   * if the new value does not
-   * conform to the pattern for
-   * this entry.
+   * The function throws an exception of type ExcValueDoesNotMatchPattern
+   * if the new value does not conform to the pattern for this entry.
    */
   void           set (const std::string &entry_name,
                       const char        *new_value);
 
   /**
-   * Change the value presently stored for
-   * <tt>entry_name</tt> to the one given
-   * in the second argument.
+   * Change the value presently stored for <tt>entry_name</tt> to the one
+   * given in the second argument.
    *
-   * The parameter must already exist in
-   * the present subsection.
+   * The parameter must already exist in the present subsection.
    *
-   * The function throws an
-   * exception of type
-   * ExcValueDoesNotMatchPattern
-   * if the new value does not
-   * conform to the pattern for
-   * this entry.
+   * The function throws an exception of type ExcValueDoesNotMatchPattern
+   * if the new value does not conform to the pattern for this entry.
    */
   void           set (const std::string &entry_name,
                       const long int    &new_value);
 
   /**
-   * Change the value presently stored for
-   * <tt>entry_name</tt> to the one given
-   * in the second argument.
+   * Change the value presently stored for <tt>entry_name</tt> to the one
+   * given in the second argument.
    *
-   * The parameter must already exist in
-   * the present subsection.
+   * The parameter must already exist in the present subsection.
    *
-   * For internal purposes, the new value
-   * needs to be converted to a
-   * string. This is done using 16 digits
-   * of accuracy, so the set value and the
-   * one you can get back out using
-   * get_double() may differ in the 16th
+   * For internal purposes, the new value needs to be converted to a
+   * string. This is done using 16 digits of accuracy, so the set value and
+   * the one you can get back out using get_double() may differ in the 16th
    * digit.
    *
-   * The function throws an
-   * exception of type
-   * ExcValueDoesNotMatchPattern
-   * if the new value does not
-   * conform to the pattern for
-   * this entry.
+   * The function throws an exception of type ExcValueDoesNotMatchPattern
+   * if the new value does not conform to the pattern for this entry.
    */
   void           set (const std::string &entry_name,
                       const double      &new_value);
 
   /**
-   * Change the value presently stored for
-   * <tt>entry_name</tt> to the one given
-   * in the second argument.
+   * Change the value presently stored for <tt>entry_name</tt> to the one
+   * given in the second argument.
    *
-   * The parameter must already exist in
-   * the present subsection.
+   * The parameter must already exist in the present subsection.
    *
-   * The function throws an
-   * exception of type
-   * ExcValueDoesNotMatchPattern
-   * if the new value does not
-   * conform to the pattern for
-   * this entry.
+   * The function throws an exception of type ExcValueDoesNotMatchPattern
+   * if the new value does not conform to the pattern for this entry.
    */
   void           set (const std::string &entry_name,
                       const bool        &new_value);
 
 
   /**
-   * Print all parameters with the
-   * given style to
-   * <tt>out</tt>. Presently only
-   * <tt>Text</tt> and <tt>LaTeX</tt> are
-   * implemented.
+   * Print all parameters with the given style to <tt>out</tt>. Presently
+   * only <tt>Text</tt> and <tt>LaTeX</tt> are implemented.
    *
-   * In <tt>Text</tt> format, the output
-   * is formatted in such a way
-   * that it is possible to use it
-   * for later input again. This is
-   * most useful to record the
-   * parameters for a specific run,
-   * since if you output the
-   * parameters using this function
-   * into a log file, you can
-   * always recover the results by
-   * simply copying the output to
-   * your input file.
+   * In <tt>Text</tt> format, the output is formatted in such a way that it
+   * is possible to use it for later input again. This is most useful to
+   * record the parameters for a specific run, since if you output the
+   * parameters using this function into a log file, you can always recover
+   * the results by simply copying the output to your input file.
    *
-   * Besides the name and value of
-   * each entry, the output also
-   * contains the default value of
-   * entries if it is different
-   * from the actual value, as well
-   * as the documenting string
-   * given to the
-   * declare_entry() function
+   * Besides the name and value of each entry, the output also contains the
+   * default value of entries if it is different from the actual value, as
+   * well as the documenting string given to the declare_entry() function
    * if available.
    *
-   * In <tt>Text</tt> format, the
-   * output contains the same information
-   * but in a format so that the
-   * resulting file can be input into
-   * a latex document such as a manual
-   * for the code for which this object
-   * handles run-time parameters.
-   * The various sections of parameters
-   * are then represented by latex
-   * section and subsection commands
-   * as well as by nested enumerations.
+   * In <tt>Text</tt> format, the output contains the same information but
+   * in a format so that the resulting file can be input into a latex
+   * document such as a manual for the code for which this object handles
+   * run-time parameters. The various sections of parameters are then
+   * represented by latex section and subsection commands as well as by
+   * nested enumerations.
    *
-   * In addition, all parameter names
-   * are listed with <code>@\index</code>
-   * statements in two indices called
-   * <code>prmindex</code> (where the
-   * name of each parameter is listed
-   * in the index) and <code>prmindexfull</code>
-   * where parameter names are listed
-   * sorted by the section in which
-   * they exist. By default, the LaTeX
-   * program ignores these <code>@\index</code>
-   * commands, but they can be used to
-   * generate an index by using the
-   * following commands in the preamble
-   * of the latex file:
+   * In addition, all parameter names are listed with <code>@\index</code>
+   * statements in two indices called <code>prmindex</code> (where the name
+   * of each parameter is listed in the index) and
+   * <code>prmindexfull</code> where parameter names are listed sorted by
+   * the section in which they exist. By default, the LaTeX program ignores
+   * these <code>@\index</code> commands, but they can be used to generate
+   * an index by using the following commands in the preamble of the latex
+   * file:
    * @code
    * \usepackage{imakeidx}
    * \makeindex[name=prmindex, title=Index of run-time parameter entries]
    * \makeindex[name=prmindexfull, title=Index of run-time parameters with section names]
    * @endcode
-   * and at the end of the file
-   * this:
+   * and at the end of the file this:
    * @code
    * \printindex[prmindex]
    * \printindex[prmindexfull]
@@ -2203,76 +1769,51 @@ public:
                                   const OutputStyle  style);
 
   /**
-   * Print out the parameters of
-   * the present subsection as
-   * given by the
-   * <tt>subsection_path</tt> member
-   * variable. This variable is
-   * controlled by entering and
-   * leaving subsections through
-   * the enter_subsection() and
-   * leave_subsection()
-   * functions.
+   * Print out the parameters of the present subsection as given by the
+   * <tt>subsection_path</tt> member variable. This variable is controlled
+   * by entering and leaving subsections through the enter_subsection() and
+   * leave_subsection() functions.
    *
-   * In most cases, you will not
-   * want to use this function
-   * directly, but have it called
-   * recursively by the previous
-   * function.
+   * In most cases, you will not want to use this function directly, but
+   * have it called recursively by the previous function.
    */
   void print_parameters_section (std::ostream       &out,
                                  const OutputStyle   style,
                                  const unsigned int  indent_level);
 
   /**
-   * Print parameters to a
-   * logstream.  This function
-   * allows to print all parameters
-   * into a log-file.  Sections
-   * will be indented in the usual
+   * Print parameters to a logstream. This function allows to print all
+   * parameters into a log-file. Sections will be indented in the usual
    * log-file style.
    */
   void log_parameters (LogStream &out);
 
   /**
-   * Log parameters in the present
-   * subsection. The subsection is
-   * determined by the
-   * <tt>subsection_path</tt> member
-   * variable. This variable is
-   * controlled by entering and
-   * leaving subsections through
-   * the enter_subsection() and
-   * leave_subsection()
-   * functions.
+   * Log parameters in the present subsection. The subsection is determined
+   * by the <tt>subsection_path</tt> member variable. This variable is
+   * controlled by entering and leaving subsections through the
+   * enter_subsection() and leave_subsection() functions.
    *
-   * In most cases, you will not
-   * want to use this function
-   * directly, but have it called
-   * recursively by the previous
-   * function.
+   * In most cases, you will not want to use this function directly, but
+   * have it called recursively by the previous function.
    */
   void log_parameters_section (LogStream &out);
 
   /**
-   * Determine an estimate for
-   * the memory consumption (in
-   * bytes) of this
+   * Determine an estimate for the memory consumption (in bytes) of this
    * object.
    */
   std::size_t memory_consumption () const;
 
   /**
-   * Write the data of this object to a
-   * stream for the purpose of
+   * Write the data of this object to a stream for the purpose of
    * serialization.
    */
   template <class Archive>
   void save (Archive &ar, const unsigned int version) const;
 
   /**
-   * Read the data of this object from a
-   * stream for the purpose of
+   * Read the data of this object from a stream for the purpose of
    * serialization.
    */
   template <class Archive>
@@ -2320,104 +1861,73 @@ public:
   //@}
 private:
   /**
-   * The separator used when
-   * accessing elements of a path
-   * into the parameter tree.
+   * The separator used when accessing elements of a path into the
+   * parameter tree.
    */
   static const char path_separator = '.';
 
   /**
-   * The complete tree of sections
-   * and entries. See the general
-   * documentation of this class
-   * for a description how data is
-   * stored in this variable.
+   * The complete tree of sections and entries. See the general
+   * documentation of this class for a description how data is stored in
+   * this variable.
    *
-   * The variable is a pointer so
-   * that we can use an incomplete
-   * type, rather than having to
-   * include all of the
-   * property_tree stuff from
-   * boost. This works around a
-   * problem with gcc 4.5.
+   * The variable is a pointer so that we can use an incomplete type,
+   * rather than having to include all of the property_tree stuff from
+   * boost. This works around a problem with gcc 4.5.
    */
   std::auto_ptr<boost::property_tree::ptree> entries;
 
   /**
-   * A list of patterns that are
-   * used to describe the
-   * parameters of this object. The
-   * are indexed by nodes in the
-   * property tree.
+   * A list of patterns that are used to describe the parameters of this
+   * object. The are indexed by nodes in the property tree.
    */
   std::vector<std_cxx1x::shared_ptr<const Patterns::PatternBase> > patterns;
 
   /**
-   * Mangle a string so that it
-   * doesn't contain any special
-   * characters or spaces.
+   * Mangle a string so that it doesn't contain any special characters or
+   * spaces.
    */
   static std::string mangle (const std::string &s);
 
   /**
-   * Unmangle a string into its
-   * original form.
+   * Unmangle a string into its original form.
    */
   static std::string demangle (const std::string &s);
 
   /**
-   * Return whether a given node is
-   * a parameter node or a
-   * subsection node.
+   * Return whether a given node is a parameter node or a subsection node.
    */
   static bool is_parameter_node (const boost::property_tree::ptree &);
 
   /**
-   * Path of presently selected
-   * subsections; empty list means
-   * top level
+   * Path of presently selected subsections; empty list means top level
    */
   std::vector<std::string> subsection_path;
 
   /**
-   * Return the string that
-   * identifies the current path
-   * into the property tree. This
-   * is only a path, i.e. it is not
-   * terminated by the
+   * Return the string that identifies the current path into the property
+   * tree. This is only a path, i.e. it is not terminated by the
    * path_separator character.
    */
   std::string get_current_path () const;
 
   /**
-   * Given the name of an entry as
-   * argument, the function
-   * computes a full path into the
-   * parameter tree using the
-   * current subsection.
+   * Given the name of an entry as argument, the function computes a full
+   * path into the parameter tree using the current subsection.
    */
   std::string get_current_full_path (const std::string &name) const;
 
   /**
-   * Scan one line of input.
-   * <tt>lineno</tt> is the number of
-   * the line presently scanned
-   * (for the logs if there are
-   * messages). Return <tt>false</tt> if
-   * line contained stuff that
-   * could not be understood, the
-   * uppermost subsection was to be
-   * left by an <tt>END</tt> or <tt>end</tt>
-   * statement, a value for a
-   * non-declared entry was given
-   * or the entry value did not
-   * match the regular
-   * expression. <tt>true</tt> otherwise.
+   * Scan one line of input. <tt>lineno</tt> is the number of the line
+   * presently scanned (for the logs if there are messages). Return
+   * <tt>false</tt> if line contained stuff that could not be understood,
+   * the uppermost subsection was to be left by an <tt>END</tt> or
+   * <tt>end</tt> statement, a value for a non-declared entry was given or
+   * the entry value did not match the regular expression. <tt>true</tt>
+   * otherwise.
    *
-   * The function modifies its
-   * argument, but also takes it by
-   * value, so the caller's
-   * variable is not changed.
+   * The function modifies its argument, but also takes it by value, so the
+   * caller's variable is not changed.
    */
   bool scan_line (std::string         line,
                   const unsigned int  lineno);
@@ -2428,57 +1938,64 @@ private:
 
 
 /**
- *   The class MultipleParameterLoop offers an easy possibility to test several
- *   parameter sets during one run of the program. For this it uses the
- *   ParameterHandler class to read in data in a standardized form, searches for
- *   variant entry values and performs a loop over all combinations of parameters.
+ *   The class MultipleParameterLoop offers an easy possibility to test
+ *   several parameter sets during one run of the program. For this it uses
+ *   the ParameterHandler class to read in data in a standardized form,
+ *   searches for variant entry values and performs a loop over all
+ *   combinations of parameters.
  *
  *   Variant entry values are given like this:
  *   @verbatim
  *     set Time step size = { 0.1 | 0.2 | 0.3 }
  *   @endverbatim
- *   The loop will then perform three runs of the program, one for each value
- *   of <tt>Time step size</tt>, while all other parameters are as specified or with their
- *   default value. If there are several variant entry values in the input, a loop is
- *   performed for each combination of variant values:
+ *   The loop will then perform three runs of the program, one for each
+ *   value of <tt>Time step size</tt>, while all other parameters are as
+ *   specified or with their default value. If there are several variant
+ *   entry values in the input, a loop is performed for each combination of
+ *   variant values:
  *   @verbatim
  *     set Time step size = { 0.1 | 0.2 }
  *     set Solver         = { CG  | GMRES }
  *   @endverbatim
- *   will result in four runs of the programs, with time step 0.1 and 0.2 for each
- *   of the two solvers.
+ *   will result in four runs of the programs, with time step 0.1 and 0.2
+ *   for each of the two solvers.
  *
- *   In addition to variant entries, this class also supports <i>array entries</i> that look like this:
+ *   In addition to variant entries, this class also supports <i>array
+ *   entries</i> that look like this:
  *   @verbatim
  *     set Output file = ofile.{{ 1 | 2 | 3 | 4 }}
  *   @endverbatim
- *   This indicates that if there are variant entries producing a total of four
- *   different runs, then we will write their results to the files <tt>ofile.1</tt>, <tt>ofile.2</tt>,
- *   <tt>ofile.3</tt> and <tt>ofile.4</tt>, respectively. Array entries do not generate multiple
- *   runs of the main loop themselves, but if there are variant entries, then in
- *   the <i>n</i>th run of the main loop, also the <i>n</i>th value of an array is returned.
- *
- *   Since the different variants are constructed in the order of declaration, not in
- *   the order in which the variant entries appear in the input file, it may be
- *   difficult to guess the mapping between the different variants and the appropriate
- *   entry in an array. You will have to check the order of declaration, or use
- *   only one variant entry.
- *
- *   It is guaranteed that only selections which match the regular expression (pattern) given
- *   upon declaration of an entry are given back to the program. If a variant value
- *   does not match the regular expression, the default value is stored and an error
- *   is issued. Before the first run of the loop, all possible values are checked
- *   for their conformance, so that the error is issued at the very beginning of the
+ *   This indicates that if there are variant entries producing a total of
+ *   four different runs, then we will write their results to the files
+ *   <tt>ofile.1</tt>, <tt>ofile.2</tt>, <tt>ofile.3</tt> and
+ *   <tt>ofile.4</tt>, respectively. Array entries do not generate multiple
+ *   runs of the main loop themselves, but if there are variant entries,
+ *   then in the <i>n</i>th run of the main loop, also the <i>n</i>th value
+ *   of an array is returned.
+ *
+ *   Since the different variants are constructed in the order of
+ *   declaration, not in the order in which the variant entries appear in
+ *   the input file, it may be difficult to guess the mapping between the
+ *   different variants and the appropriate entry in an array. You will
+ *   have to check the order of declaration, or use only one variant entry.
+ *
+ *   It is guaranteed that only selections which match the regular
+ *   expression (pattern) given upon declaration of an entry are given back
+ *   to the program. If a variant value does not match the regular
+ *   expression, the default value is stored and an error is issued. Before
+ *   the first run of the loop, all possible values are checked for their
+ *   conformance, so that the error is issued at the very beginning of the
  *   program.
  *
  *
  *   <h3>Usage</h3>
  *
- *   The usage of this class is similar to the ParameterHandler class. First the
- *   entries and subsections have to be declared, then a loop is performed in which
- *   the different parameter sets are set, a new instance of a user class is created
- *   which is then called. Taking the classes of the example for the
- *   ParameterHandler class, the extended program would look like this:
+ *   The usage of this class is similar to the ParameterHandler class.
+ *   First the entries and subsections have to be declared, then a loop is
+ *   performed in which the different parameter sets are set, a new
+ *   instance of a user class is created which is then called. Taking the
+ *   classes of the example for the ParameterHandler class, the extended
+ *   program would look like this:
  *   @code
  *     class HelperClass : public MultipleParameterLoop::UserClass {
  *       public:
@@ -2525,25 +2042,25 @@ private:
  *     }
  *   @endcode
  *
- *   As can be seen, first a new helper class has to be set up. This must contain
- *   a virtual constructor for a problem class. You can also derive your problem
- *   class from MultipleParameterLoop::UserClass and let <tt>create_new</tt> clear all
- *   member variables. If you have access to all inherited member variables in
- *   some way this is the recommended procedure. A third possibility is to use
- *   multiple inheritance and derive a helper class from both the
- *   MultipleParameterLoop::UserClass and the problem class. In any case,
- *   <tt>create_new</tt> has to provide a clean problem object which is the problem in
- *   the second and third possibility.
- *
- *   The derived class also
- *   has to provide for member functions which declare the entries and which run
- *   the program. Running the program includes getting the parameters out of the
- *   ParameterHandler object.
+ *   As can be seen, first a new helper class has to be set up. This must
+ *   contain a virtual constructor for a problem class. You can also derive
+ *   your problem class from MultipleParameterLoop::UserClass and let
+ *   <tt>create_new</tt> clear all member variables. If you have access to
+ *   all inherited member variables in some way this is the recommended
+ *   procedure. A third possibility is to use multiple inheritance and
+ *   derive a helper class from both the MultipleParameterLoop::UserClass
+ *   and the problem class. In any case, <tt>create_new</tt> has to provide
+ *   a clean problem object which is the problem in the second and third
+ *   possibility.
+ *
+ *   The derived class also has to provide for member functions which
+ *   declare the entries and which run the program. Running the program
+ *   includes getting the parameters out of the ParameterHandler object.
  *
  *   After defining an object of this helper class and an object of the
- *   MultipleParameterLoop class, the entries have to be declared in the same way
- *   as for the ParameterHandler class. Then the input has to be read. Finally
- *   the loop is called. This executes the following steps:
+ *   MultipleParameterLoop class, the entries have to be declared in the
+ *   same way as for the ParameterHandler class. Then the input has to be
+ *   read. Finally the loop is called. This executes the following steps:
  *   @code
  *     for (each combination)
  *       {
@@ -2554,9 +2071,9 @@ private:
  *         UserObject.run (*this);
  *       }
  *   @endcode
- *   <tt>UserObject</tt> is the parameter to the <tt>loop</tt> function. <tt>create_new</tt> is given the number
- *   of the run (starting from one) to enable naming output files differently for each
*   run.
+ *   <tt>UserObject</tt> is the parameter to the <tt>loop</tt> function.
+ *   <tt>create_new</tt> is given the number of the run (starting from one)
 *   to enable naming output files differently for each run.
  *
  *
  *   <h3>Syntax for variant and array entry values</h3>
@@ -2574,8 +2091,8 @@ private:
  *
  *   <h3>Worked example</h3>
  *
- *   Given the above extensions to the example program for the ParameterHandler and the
- *   following input file
+ *   Given the above extensions to the example program for the
+ *   ParameterHandler and the following input file
  *   @verbatim
  *     set Equation 1 = Poisson
  *     set Equation 2 = Navier-Stokes
@@ -2630,8 +2147,8 @@ private:
  *              eq1=Poisson, eq2=Navier-Stokes
  *              Matrix1=Sparse, Matrix2=Full
  *   @endverbatim
- *   Since <tt>create_new</tt> gets the number of the run it would also be possible to output
- *   the number of the run.
+ *   Since <tt>create_new</tt> gets the number of the run it would also be
+ *   possible to output the number of the run.
  *
  *
  *   @ingroup input
@@ -2641,37 +2158,32 @@ class MultipleParameterLoop : public ParameterHandler
 {
 public:
   /**
-   * This is the class the helper class or the
-   * problem class has to be derived of.
+   * This is the class the helper class or the problem class has to be
+   * derived of.
    */
   class UserClass
   {
   public:
     /**
-     * Destructor. It doesn't actually do
-     * anything, but is declared to force
-     * derived classes to have a virtual
-     * destructor.
+     * Destructor. It doesn't actually do anything, but is declared to
+     * force derived classes to have a virtual destructor.
      */
     virtual ~UserClass ();
 
     /**
-     * <tt>create_new</tt> must provide a clean
-     * object, either by creating a new one
-     * or by cleaning an old one.
+     * <tt>create_new</tt> must provide a clean object, either by creating
+     * a new one or by cleaning an old one.
      */
     virtual void create_new (const unsigned int run_no) = 0;
 
     /**
-     * This should declare parameters and call
-     * the <tt>declare_parameters</tt> function of the
-     * problem class.
+     * This should declare parameters and call the
+     * <tt>declare_parameters</tt> function of the problem class.
      */
     virtual void declare_parameters (ParameterHandler &prm) = 0;
 
     /**
-     * Get the parameters and run any
-     * necessary action.
+     * Get the parameters and run any necessary action.
      */
     virtual void run (ParameterHandler &prm) = 0;
   };
@@ -2682,10 +2194,9 @@ public:
   MultipleParameterLoop ();
 
   /**
-   * Destructor. Declare this only to have
-   * a virtual destructor, which is safer
-   * as we have virtual functions.
-   * It actually does nothing spectacular.
+   * Destructor. Declare this only to have a virtual destructor, which is
+   * safer as we have virtual functions. It actually does nothing
+   * spectacular.
    */
   virtual ~MultipleParameterLoop ();
 
@@ -2695,9 +2206,8 @@ public:
                            const bool write_stripped_file = false);
 
   /**
-   * Read input from a string in memory. The
-   *  lines in memory have to be separated by
-   *  <tt>@\n</tt> characters.
+   * Read input from a string in memory. The lines in memory have to be
+   * separated by <tt>@\n</tt> characters.
    */
   virtual bool read_input_from_string (const char *s);
 
@@ -2707,9 +2217,7 @@ public:
   void loop (UserClass &uc);
 
   /**
-   * Determine an estimate for
-   * the memory consumption (in
-   * bytes) of this
+   * Determine an estimate for the memory consumption (in bytes) of this
    * object.
    */
   std::size_t memory_consumption () const;
@@ -2717,17 +2225,14 @@ public:
 private:
 
   /**
-   * An object in the list of entries with
-   * multiple values.
+   * An object in the list of entries with multiple values.
    */
   class Entry
   {
   public:
     /**
-     * Declare what a multiple entry
-     * is: a variant * entry (in
-     * curly braces <tt>{</tt>, <tt>}</tt>) or an
-     * array (in double curly braces
+     * Declare what a multiple entry is: a variant * entry (in curly braces
+     * <tt>{</tt>, <tt>}</tt>) or an array (in double curly braces
      * <tt>{{</tt>, <tt>}}</tt>).
      */
     enum MultipleEntryType
@@ -2741,18 +2246,16 @@ private:
     Entry () : type (array) {}
 
     /**
-     * Construct an object with given subsection
-     * path, name and value. The splitting up
-     * into the different variants is done
-     * later by <tt>split_different_values</tt>.
+     * Construct an object with given subsection path, name and value. The
+     * splitting up into the different variants is done later by
+     * <tt>split_different_values</tt>.
      */
     Entry (const std::vector<std::string> &Path,
            const std::string              &Name,
            const std::string              &Value);
 
     /**
-     * Split the entry value into the different
-     * branches.
+     * Split the entry value into the different branches.
      */
     void split_different_values ();
 
@@ -2772,22 +2275,18 @@ private:
     std::string         entry_value;
 
     /**
-     * List of entry values constructed out of
-     * what was given in the input file (that
-     * is stored in EntryValue.
+     * List of entry values constructed out of what was given in the input
+     * file (that is stored in EntryValue.
      */
     std::vector<std::string> different_values;
 
     /**
-     * Store whether this entry is a variant
-     * entry or an array.
+     * Store whether this entry is a variant entry or an array.
      */
     MultipleEntryType      type;
 
     /**
-     * Determine an estimate for
-     * the memory consumption (in
-     * bytes) of this
+     * Determine an estimate for the memory consumption (in bytes) of this
      * object.
      */
     std::size_t memory_consumption () const;
@@ -2799,37 +2298,26 @@ private:
   std::vector<Entry> multiple_choices;
 
   /**
-   * Number of branches constructed
-   * from the different
-   * combinations of the variants.
-   * This obviously equals the
-   * number of runs to be
-   * performed.
+   * Number of branches constructed from the different combinations of the
+   * variants. This obviously equals the number of runs to be performed.
    */
   unsigned int n_branches;
 
   /**
-   * Initialize the different
-   * branches, i.e.  construct the
-   * combinations.
+   * Initialize the different branches, i.e.  construct the combinations.
    */
   void init_branches ();
 
   /**
-   * Traverse the section currently
-   * set by
-   * enter_subsection()/leave_subsection()
-   * and see which of the entries
-   * are variante/array
-   * entries. Then fill the
-   * multiple_choices variable
-   * using this information.
+   * Traverse the section currently set by
+   * enter_subsection()/leave_subsection() and see which of the entries are
+   * variante/array entries. Then fill the multiple_choices variable using
+   * this information.
    */
   void init_branches_current_section ();
 
   /**
-   * Transfer the entry values for one run
-   * to the entry tree.
+   * Transfer the entry values for one run to the entry tree.
    */
   void fill_entry_values (const unsigned int run_no);
 };

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.