]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
Reindent/refill comments in a few files to improve readability.
authorkronbichler <kronbichler@0785d39b-7218-0410-832d-ea1e28bc413d>
Sun, 9 Dec 2012 09:55:15 +0000 (09:55 +0000)
committerkronbichler <kronbichler@0785d39b-7218-0410-832d-ea1e28bc413d>
Sun, 9 Dec 2012 09:55:15 +0000 (09:55 +0000)
git-svn-id: https://svn.dealii.org/trunk@27783 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/include/deal.II/lac/sparse_matrix.h
deal.II/include/deal.II/lac/sparse_matrix.templates.h
deal.II/include/deal.II/lac/sparsity_pattern.h

index 6ec462b0f66cf8312df92a7c9d2b8d6cb822e6d3..9092530630d276188d6485fcd872cb3cc43cd90b 100644 (file)
@@ -43,21 +43,14 @@ namespace SparseMatrixIterators
   class Iterator;
 
   /**
-   * General template for sparse matrix
-   * accessors. The first template argument
-   * denotes the underlying numeric type,
-   * the second the constness of the
+   * General template for sparse matrix accessors. The first template argument
+   * denotes the underlying numeric type, the second the constness of the
    * matrix.
    *
-   * The general template is not
-   * implemented, only the
-   * specializations for the two
-   * possible values of the second
-   * template argument. Therefore,
-   * the interface listed here only
-   * serves as a template provided
-   * since doxygen does not link the
-   * specializations.
+   * The general template is not implemented, only the specializations for the
+   * two possible values of the second template argument. Therefore, the
+   * interface listed here only serves as a template provided since doxygen
+   * does not link the specializations.
    */
   template <typename number, bool Constness>
   class Accessor : public SparsityPatternIterators::Accessor
@@ -74,11 +67,8 @@ namespace SparseMatrixIterators
     number &value();
 
     /**
-     * Return a reference to the matrix
-     * into which this accessor
-     * points. Note that in the present
-     * case, this is a constant
-     * reference.
+     * Return a reference to the matrix into which this accessor points. Note
+     * that in the present case, this is a constant reference.
      */
     const SparseMatrix<number> &get_matrix () const;
   };
@@ -86,23 +76,18 @@ namespace SparseMatrixIterators
 
 
   /**
-   * Accessor class for constant matrices,
-   * used in the const_iterators. This
-   * class builds on the accessor classes
-   * used for sparsity patterns to loop
-   * over all nonzero entries, and only
-   * adds the accessor functions to gain
-   * access to the actual value stored at a
-   * certain location.
+   * Accessor class for constant matrices, used in the const_iterators. This
+   * class builds on the accessor classes used for sparsity patterns to loop
+   * over all nonzero entries, and only adds the accessor functions to gain
+   * access to the actual value stored at a certain location.
    */
   template <typename number>
   class Accessor<number,true> : public SparsityPatternIterators::Accessor
   {
   public:
     /**
-     * Typedef for the type (including
-     * constness) of the matrix to be
-     * used here.
+     * Typedef for the type (including constness) of the matrix to be used
+     * here.
      */
     typedef const SparseMatrix<number> MatrixType;
 
@@ -114,15 +99,12 @@ namespace SparseMatrixIterators
               const unsigned int  index);
 
     /**
-     * Constructor. Construct the end
-     * accessor for the given matrix.
+     * Constructor. Construct the end accessor for the given matrix.
      */
     Accessor (MatrixType         *matrix);
 
     /**
-     * Copy constructor to get from a
-     * non-const accessor to a const
-     * accessor.
+     * Copy constructor to get from a non-const accessor to a const accessor.
      */
     Accessor (const SparseMatrixIterators::Accessor<number,false> &a);
 
@@ -132,11 +114,8 @@ namespace SparseMatrixIterators
     number value() const;
 
     /**
-     * Return a reference to the matrix
-     * into which this accessor
-     * points. Note that in the present
-     * case, this is a constant
-     * reference.
+     * Return a reference to the matrix into which this accessor points. Note
+     * that in the present case, this is a constant reference.
      */
     MatrixType &get_matrix () const;
 
@@ -147,8 +126,7 @@ namespace SparseMatrixIterators
     MatrixType *matrix;
 
     /**
-     * Make the advance function of the
-     * base class available.
+     * Make the advance function of the base class available.
      */
     using SparsityPatternIterators::Accessor::advance;
 
@@ -161,126 +139,91 @@ namespace SparseMatrixIterators
 
 
   /**
-   * Accessor class for non-constant
-   * matrices, used in the iterators. This
-   * class builds on the accessor classes
-   * used for sparsity patterns to loop
-   * over all nonzero entries, and only
-   * adds the accessor functions to gain
-   * access to the actual value stored at a
-   * certain location.
+   * Accessor class for non-constant matrices, used in the iterators. This
+   * class builds on the accessor classes used for sparsity patterns to loop
+   * over all nonzero entries, and only adds the accessor functions to gain
+   * access to the actual value stored at a certain location.
    */
   template <typename number>
   class Accessor<number,false> : public SparsityPatternIterators::Accessor
   {
   private:
     /**
-     * Reference class. This is what the
-     * accessor class returns when you
-     * call the value() function. The
-     * reference acts just as if it were
-     * a reference to the actual value of
-     * a matrix entry, i.e. you can read
-     * and write it, you can add and
-     * multiply to it, etc, but since the
-     * matrix does not give away the
-     * address of this matrix entry, we
-     * have to go through functions to do
-     * all this.
+     * Reference class. This is what the accessor class returns when you call
+     * the value() function. The reference acts just as if it were a reference
+     * to the actual value of a matrix entry, i.e. you can read and write it,
+     * you can add and multiply to it, etc, but since the matrix does not give
+     * away the address of this matrix entry, we have to go through functions
+     * to do all this.
      *
-     * The constructor takes a pointer to
-     * an accessor object that describes
-     * which element of the matrix it
-     * points to. This creates an
-     * ambiguity when one writes code
-     * like iterator->value()=0 (instead
-     * of iterator->value()=0.0), since
-     * the right hand side is an integer
-     * that can both be converted to a
-     * <tt>number</tt> (i.e., most
-     * commonly a double) or to another
-     * object of type
-     * <tt>Reference</tt>. The compiler
-     * then complains about not knowing
-     * which conversion to take.
+     * The constructor takes a pointer to an accessor object that describes
+     * which element of the matrix it points to. This creates an ambiguity
+     * when one writes code like iterator->value()=0 (instead of
+     * iterator->value()=0.0), since the right hand side is an integer that
+     * can both be converted to a <tt>number</tt> (i.e., most commonly a
+     * double) or to another object of type <tt>Reference</tt>. The compiler
+     * then complains about not knowing which conversion to take.
      *
-     * For some reason, adding another
-     * overload operator=(int) doesn't
-     * seem to cure the problem. We avoid
-     * it, however, by adding a second,
-     * dummy argument to the Reference
-     * constructor, that is unused, but
-     * makes sure there is no second
-     * matching conversion sequence using
-     * a one-argument right hand side.
+     * For some reason, adding another overload operator=(int) doesn't seem to
+     * cure the problem. We avoid it, however, by adding a second, dummy
+     * argument to the Reference constructor, that is unused, but makes sure
+     * there is no second matching conversion sequence using a one-argument
+     * right hand side.
      *
-     * The testcase oliver_01 checks that
-     * this actually works as intended.
+     * The testcase oliver_01 checks that this actually works as intended.
      */
     class Reference
     {
     public:
       /**
-       * Constructor. For the second
-       * argument, see the general
-       * class documentation.
+       * Constructor. For the second argument, see the general class
+       * documentation.
        */
       Reference (const Accessor *accessor,
                  const bool dummy);
 
       /**
-       * Conversion operator to the
-       * data type of the matrix.
+       * Conversion operator to the data type of the matrix.
        */
       operator number () const;
 
       /**
-       * Set the element of the matrix
-       * we presently point to to @p n.
+       * Set the element of the matrix we presently point to to @p n.
        */
       const Reference &operator = (const number n) const;
 
       /**
-       * Add @p n to the element of the
-       * matrix we presently point to.
+       * Add @p n to the element of the matrix we presently point to.
        */
       const Reference &operator += (const number n) const;
 
       /**
-       * Subtract @p n from the element
-       * of the matrix we presently
-       * point to.
+       * Subtract @p n from the element of the matrix we presently point to.
        */
       const Reference &operator -= (const number n) const;
 
       /**
-       * Multiply the element of the
-       * matrix we presently point to
-       * by @p n.
+       * Multiply the element of the matrix we presently point to by @p n.
        */
       const Reference &operator *= (const number n) const;
 
       /**
-       * Divide the element of the
-       * matrix we presently point to
-       * by @p n.
+       * Divide the element of the matrix we presently point to by @p n.
        */
       const Reference &operator /= (const number n) const;
 
     private:
       /**
-       * Pointer to the accessor that
-       * denotes which element we
-       * presently point to.
+       * Pointer to the accessor that denotes which element we presently point
+       * to.
        */
       const Accessor *accessor;
     };
 
   public:
     /**
-     * Typedef for the type (including
-     * constness) of the matrix to be
-     * used here.
+     * Typedef for the type (including constness) of the matrix to be used
+     * here.
      */
     typedef SparseMatrix<number> MatrixType;
 
@@ -292,24 +235,18 @@ namespace SparseMatrixIterators
               const unsigned int  index);
 
     /**
-     * Constructor. Construct the end
-     * accessor for the given matrix.
+     * Constructor. Construct the end accessor for the given matrix.
      */
     Accessor (MatrixType         *matrix);
 
     /**
-     * Value of this matrix entry,
-     * returned as a read- and writable
-     * reference.
+     * Value of this matrix entry, returned as a read- and writable reference.
      */
     Reference value() const;
 
     /**
-     * Return a reference to the matrix
-     * into which this accessor
-     * points. Note that in the present
-     * case, this is a non-constant
-     * reference.
+     * Return a reference to the matrix into which this accessor points. Note
+     * that in the present case, this is a non-constant reference.
      */
     MatrixType &get_matrix () const;
 
@@ -320,8 +257,7 @@ namespace SparseMatrixIterators
     MatrixType *matrix;
 
     /**
-     * Make the advance function of the
-     * base class available.
+     * Make the advance function of the base class available.
      */
     using SparsityPatternIterators::Accessor::advance;
 
@@ -332,59 +268,49 @@ namespace SparseMatrixIterators
     friend class Iterator;
 
     /**
-     * Make the inner reference class a
-     * friend if the compiler has a bug
-     * and requires this.
+     * Make the inner reference class a friend if the compiler has a bug and
+     * requires this.
      */
   };
 
 
 
   /**
-   * STL conforming iterator for constant
-   * and non-constant matrices.
+   * STL conforming iterator for constant and non-constant matrices.
    *
-   * The first template argument
-   * denotes the underlying numeric type,
-   * the second the constness of the
-   * matrix.
+   * The first template argument denotes the underlying numeric type, the
+   * second the constness of the matrix.
    *
-   * Since there is a specialization of
-   * this class for
-   * <tt>Constness=false</tt>, this class
-   * is for iterators to constant matrices.
+   * Since there is a specialization of this class for
+   * <tt>Constness=false</tt>, this class is for iterators to constant
+   * matrices.
    */
   template <typename number, bool Constness>
   class Iterator
   {
   public:
     /**
-     * Typedef for the matrix type
-     * (including constness) we are to
-     * operate on.
+     * Typedef for the matrix type (including constness) we are to operate on.
      */
     typedef
     typename Accessor<number,Constness>::MatrixType
     MatrixType;
 
     /**
-     * Constructor. Create an iterator
-     * into the matrix @p matrix for the
-     * given row and the index within it.
+     * Constructor. Create an iterator into the matrix @p matrix for the given
+     * row and the index within it.
      */
     Iterator (MatrixType        *matrix,
               const unsigned int row,
               const unsigned int index);
 
     /**
-     * Constructor. Create the end
-     * iterator for the given matrix.
+     * Constructor. Create the end iterator for the given matrix.
      */
     Iterator (MatrixType *matrix);
 
     /**
-     * Conversion constructor to get from
-     * a non-const iterator to a const
+     * Conversion constructor to get from a non-const iterator to a const
      * iterator.
      */
     Iterator (const SparseMatrixIterators::Iterator<number,false> &i);
@@ -410,10 +336,7 @@ namespace SparseMatrixIterators
     const Accessor<number,Constness> *operator-> () const;
 
     /**
-     * Comparison. True, if
-     * both iterators point to
-     * the same matrix
-     * position.
+     * Comparison. True, if both iterators point to the same matrix position.
      */
     bool operator == (const Iterator &) const;
 
@@ -423,29 +346,23 @@ namespace SparseMatrixIterators
     bool operator != (const Iterator &) const;
 
     /**
-     * Comparison operator. Result is
-     * true if either the first row
-     * number is smaller or if the row
-     * numbers are equal and the first
-     * index is smaller.
+     * Comparison operator. Result is true if either the first row number is
+     * smaller or if the row numbers are equal and the first index is smaller.
      *
-     * This function is only valid if
-     * both iterators point into the same
+     * This function is only valid if both iterators point into the same
      * matrix.
      */
     bool operator < (const Iterator &) const;
 
     /**
-     * Comparison operator. Works in the
-     * same way as above operator, just
-     * the other way round.
+     * Comparison operator. Works in the same way as above operator, just the
+     * other way round.
      */
     bool operator > (const Iterator &) const;
 
   private:
     /**
-     * Store an object of the
-     * accessor class.
+     * Store an object of the accessor class.
      */
     Accessor<number,Constness> accessor;
   };
@@ -476,37 +393,24 @@ class SparseMatrix : public virtual Subscriptor
 {
 public:
   /**
-   * Type of matrix entries. In analogy to
-   * the STL container classes.
+   * Type of matrix entries. In analogy to the STL container classes.
    */
   typedef number value_type;
 
   /**
-   * Declare a type that has holds
-   * real-valued numbers with the
-   * same precision as the template
-   * argument to this class. If the
-   * template argument of this
-   * class is a real data type,
-   * then real_type equals the
-   * template argument. If the
-   * template argument is a
-   * std::complex type then
-   * real_type equals the type
-   * underlying the complex
-   * numbers.
-   *
-   * This typedef is used to
-   * represent the return type of
-   * norms.
+   * Declare a type that has holds real-valued numbers with the same precision
+   * as the template argument to this class. If the template argument of this
+   * class is a real data type, then real_type equals the template
+   * argument. If the template argument is a std::complex type then real_type
+   * equals the type underlying the complex numbers.
+   *
+   * This typedef is used to represent the return type of norms.
    */
   typedef typename numbers::NumberTraits<number>::real_type real_type;
 
   /**
-   * Typedef of an STL conforming iterator
-   * class walking over all the nonzero
-   * entries of this matrix. This iterator
-   * cannot change the values of the
+   * Typedef of an STL conforming iterator class walking over all the nonzero
+   * entries of this matrix. This iterator cannot change the values of the
    * matrix.
    */
   typedef
@@ -514,34 +418,26 @@ public:
   const_iterator;
 
   /**
-   * Typedef of an STL conforming iterator
-   * class walking over all the nonzero
-   * entries of this matrix. This iterator
-   * @em can change the values of the
-   * matrix, but of course can't change the
-   * sparsity pattern as this is fixed once
-   * a sparse matrix is attached to it.
+   * Typedef of an STL conforming iterator class walking over all the nonzero
+   * entries of this matrix. This iterator @em can change the values of the
+   * matrix, but of course can't change the sparsity pattern as this is fixed
+   * once a sparse matrix is attached to it.
    */
   typedef
   SparseMatrixIterators::Iterator<number,false>
   iterator;
 
   /**
-   * A structure that describes some of the
-   * traits of this class in terms of its
-   * run-time behavior. Some other classes
-   * (such as the block matrix classes)
-   * that take one or other of the matrix
-   * classes as its template parameters can
-   * tune their behavior based on the
-   * variables in this class.
+   * A structure that describes some of the traits of this class in terms of
+   * its run-time behavior. Some other classes (such as the block matrix
+   * classes) that take one or other of the matrix classes as its template
+   * parameters can tune their behavior based on the variables in this class.
    */
   struct Traits
   {
     /**
-     * It is safe to elide additions of
-     * zeros to individual elements of
-     * this matrix.
+     * It is safe to elide additions of zeros to individual elements of this
+     * matrix.
      */
     static const bool zero_addition_can_be_elided = true;
   };
@@ -551,172 +447,106 @@ public:
    */
 //@{
   /**
-   * Constructor; initializes the matrix to
-   * be empty, without any structure, i.e.
-   * the matrix is not usable at all. This
-   * constructor is therefore only useful
-   * for matrices which are members of a
-   * class. All other matrices should be
-   * created at a point in the data flow
-   * where all necessary information is
-   * available.
+   * Constructor; initializes the matrix to be empty, without any structure,
+   * i.e.  the matrix is not usable at all. This constructor is therefore only
+   * useful for matrices which are members of a class. All other matrices
+   * should be created at a point in the data flow where all necessary
+   * information is available.
    *
-   * You have to initialize
-   * the matrix before usage with
-   * reinit(const SparsityPattern&).
+   * You have to initialize the matrix before usage with reinit(const
+   * SparsityPattern&).
    */
   SparseMatrix ();
 
   /**
-   * Copy constructor. This constructor is
-   * only allowed to be called if the matrix
-   * to be copied is empty. This is for the
-   * same reason as for the
-   * SparsityPattern, see there for the
-   * details.
+   * Copy constructor. This constructor is only allowed to be called if the
+   * matrix to be copied is empty. This is for the same reason as for the
+   * SparsityPattern, see there for the details.
    *
-   * If you really want to copy a whole
-   * matrix, you can do so by using the
+   * If you really want to copy a whole matrix, you can do so by using the
    * copy_from() function.
    */
   SparseMatrix (const SparseMatrix &);
 
   /**
-   * Constructor. Takes the given
-   * matrix sparsity structure to
-   * represent the sparsity pattern
-   * of this matrix. You can change
-   * the sparsity pattern later on
-   * by calling the reinit(const
-   * SparsityPattern&) function.
-   *
-   * You have to make sure that the
-   * lifetime of the sparsity
-   * structure is at least as long
-   * as that of this matrix or as
-   * long as reinit(const
-   * SparsityPattern&) is not
-   * called with a new sparsity
-   * pattern.
-   *
-   * The constructor is marked
-   * explicit so as to disallow
-   * that someone passes a sparsity
-   * pattern in place of a sparse
-   * matrix to some function, where
-   * an empty matrix would be
-   * generated then.
+   * Constructor. Takes the given matrix sparsity structure to represent the
+   * sparsity pattern of this matrix. You can change the sparsity pattern
+   * later on by calling the reinit(const SparsityPattern&) function.
+   *
+   * You have to make sure that the lifetime of the sparsity structure is at
+   * least as long as that of this matrix or as long as reinit(const
+   * SparsityPattern&) is not called with a new sparsity pattern.
+   *
+   * The constructor is marked explicit so as to disallow that someone passes
+   * a sparsity pattern in place of a sparse matrix to some function, where an
+   * empty matrix would be generated then.
    */
   explicit SparseMatrix (const SparsityPattern &sparsity);
 
   /**
-   * Copy constructor: initialize
-   * the matrix with the identity
-   * matrix. This constructor will
-   * throw an exception if the
-   * sizes of the sparsity pattern
-   * and the identity matrix do not
-   * coincide, or if the sparsity
-   * pattern does not provide for
-   * nonzero entries on the entire
-   * diagonal.
+   * Copy constructor: initialize the matrix with the identity matrix. This
+   * constructor will throw an exception if the sizes of the sparsity pattern
+   * and the identity matrix do not coincide, or if the sparsity pattern does
+   * not provide for nonzero entries on the entire diagonal.
    */
   SparseMatrix (const SparsityPattern &sparsity,
                 const IdentityMatrix &id);
 
   /**
-   * Destructor. Free all memory, but do not
-   * release the memory of the sparsity
-   * structure.
+   * Destructor. Free all memory, but do not release the memory of the
+   * sparsity structure.
    */
   virtual ~SparseMatrix ();
 
   /**
-   * Copy operator. Since copying
-   * entire sparse matrices is a
-   * very expensive operation, we
-   * disallow doing so except for
-   * the special case of empty
-   * matrices of size zero. This
-   * doesn't seem particularly
-   * useful, but is exactly what
-   * one needs if one wanted to
-   * have a
-   * <code>std::vector@<SparseMatrix@<double@>
-   * @></code>: in that case, one
-   * can create a vector (which
-   * needs the ability to copy
-   * objects) of empty matrices
-   * that are then later filled
-   * with something useful.
+   * Copy operator. Since copying entire sparse matrices is a very expensive
+   * operation, we disallow doing so except for the special case of empty
+   * matrices of size zero. This doesn't seem particularly useful, but is
+   * exactly what one needs if one wanted to have a
+   * <code>std::vector@<SparseMatrix@<double@> @></code>: in that case, one
+   * can create a vector (which needs the ability to copy objects) of empty
+   * matrices that are then later filled with something useful.
    */
   SparseMatrix<number> &operator = (const SparseMatrix<number> &);
 
   /**
-   * Copy operator: initialize
-   * the matrix with the identity
-   * matrix. This operator will
-   * throw an exception if the
-   * sizes of the sparsity pattern
-   * and the identity matrix do not
-   * coincide, or if the sparsity
-   * pattern does not provide for
-   * nonzero entries on the entire
-   * diagonal.
+   * Copy operator: initialize the matrix with the identity matrix. This
+   * operator will throw an exception if the sizes of the sparsity pattern and
+   * the identity matrix do not coincide, or if the sparsity pattern does not
+   * provide for nonzero entries on the entire diagonal.
    */
   SparseMatrix<number> &
   operator= (const IdentityMatrix &id);
 
   /**
-   * This operator assigns a scalar to
-   * a matrix. Since this does usually
-   * not make much sense (should we set
-   * all matrix entries to this value?
-   * Only the nonzero entries of the
-   * sparsity pattern?), this operation
-   * is only allowed if the actual
-   * value to be assigned is zero. This
-   * operator only exists to allow for
-   * the obvious notation
-   * <tt>matrix=0</tt>, which sets all
-   * elements of the matrix to zero,
-   * but keep the sparsity pattern
+   * This operator assigns a scalar to a matrix. Since this does usually not
+   * make much sense (should we set all matrix entries to this value?  Only
+   * the nonzero entries of the sparsity pattern?), this operation is only
+   * allowed if the actual value to be assigned is zero. This operator only
+   * exists to allow for the obvious notation <tt>matrix=0</tt>, which sets
+   * all elements of the matrix to zero, but keep the sparsity pattern
    * previously used.
    */
   SparseMatrix &operator = (const double d);
 
   /**
-   * Reinitialize the sparse matrix
-   * with the given sparsity
-   * pattern. The latter tells the
-   * matrix how many nonzero
-   * elements there need to be
+   * Reinitialize the sparse matrix with the given sparsity pattern. The
+   * latter tells the matrix how many nonzero elements there need to be
    * reserved.
    *
-   * Regarding memory allocation,
-   * the same applies as said
-   * above.
-   *
-   * You have to make sure that the
-   * lifetime of the sparsity
-   * structure is at least as long
-   * as that of this matrix or as
-   * long as reinit(const
-   * SparsityPattern &) is not
-   * called with a new sparsity
-   * structure.
+   * Regarding memory allocation, the same applies as said above.
+   *
+   * You have to make sure that the lifetime of the sparsity structure is at
+   * least as long as that of this matrix or as long as reinit(const
+   * SparsityPattern &) is not called with a new sparsity structure.
    *
-   * The elements of the matrix are
-   * set to zero by this function.
+   * The elements of the matrix are set to zero by this function.
    */
   virtual void reinit (const SparsityPattern &sparsity);
 
   /**
-   * Release all memory and return
-   * to a state just like after
-   * having called the default
-   * constructor. It also forgets
-   * the sparsity pattern it was
+   * Release all memory and return to a state just like after having called
+   * the default constructor. It also forgets the sparsity pattern it was
    * previously tied to.
    */
   virtual void clear ();
@@ -726,83 +556,59 @@ public:
    */
 //@{
   /**
-   * Return whether the object is
-   * empty. It is empty if either
-   * both dimensions are zero or no
-   * SparsityPattern is
-   * associated.
+   * Return whether the object is empty. It is empty if either both dimensions
+   * are zero or no SparsityPattern is associated.
    */
   bool empty () const;
 
   /**
-   * Return the dimension of the
-   * image space.  To remember: the
-   * matrix is of dimension
-   * $m \times n$.
+   * Return the dimension of the image space. To remember: the matrix is of
+   * dimension $m \times n$.
    */
   unsigned int m () const;
 
   /**
-   * Return the dimension of the
-   * range space.  To remember: the
-   * matrix is of dimension
-   * $m \times n$.
+   * Return the dimension of the range space. To remember: the matrix is of
+   * dimension $m \times n$.
    */
   unsigned int n () const;
 
   /**
-   * Return the number of entries
-   * in a specific row.
+   * Return the number of entries in a specific row.
    */
   unsigned int get_row_length (const unsigned int row) const;
 
   /**
-   * Return the number of nonzero
-   * elements of this
-   * matrix. Actually, it returns
-   * the number of entries in the
-   * sparsity pattern; if any of
-   * the entries should happen to
-   * be zero, it is counted anyway.
+   * Return the number of nonzero elements of this matrix. Actually, it
+   * returns the number of entries in the sparsity pattern; if any of the
+   * entries should happen to be zero, it is counted anyway.
    */
   unsigned int n_nonzero_elements () const;
 
   /**
-   * Return the number of actually
-   * nonzero elements of this matrix. It
-   * is possible to specify the parameter
-   * <tt>threshold</tt> in order to count
-   * only the elements that have absolute
-   * value greater than the threshold.
+   * Return the number of actually nonzero elements of this matrix. It is
+   * possible to specify the parameter <tt>threshold</tt> in order to count
+   * only the elements that have absolute value greater than the threshold.
    *
-   * Note, that this function does (in
-   * contrary to n_nonzero_elements())
-   * not count all entries of the
-   * sparsity pattern but only the ones
-   * that are nonzero (or whose absolute
-   * value is greater than threshold).
+   * Note, that this function does (in contrary to n_nonzero_elements()) not
+   * count all entries of the sparsity pattern but only the ones that are
+   * nonzero (or whose absolute value is greater than threshold).
    */
   unsigned int n_actually_nonzero_elements (const double threshold = 0.) const;
 
   /**
-   * Return a (constant) reference
-   * to the underlying sparsity
-   * pattern of this matrix.
+   * Return a (constant) reference to the underlying sparsity pattern of this
+   * matrix.
    *
-   * Though the return value is
-   * declared <tt>const</tt>, you
-   * should be aware that it may
-   * change if you call any
-   * nonconstant function of
-   * objects which operate on it.
+   * Though the return value is declared <tt>const</tt>, you should be aware
+   * that it may change if you call any nonconstant function of objects which
+   * operate on it.
    */
   const SparsityPattern &get_sparsity_pattern () const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object. See
-   * MemoryConsumption.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object. See MemoryConsumption.
    */
   std::size_t memory_consumption () const;
 
@@ -812,44 +618,28 @@ public:
    */
 //@{
   /**
-   * Set the element (<i>i,j</i>)
-   * to <tt>value</tt>. Throws an
-   * error if the entry does not
-   * exist or if <tt>value</tt> is
-   * not a finite number. Still, it
-   * is allowed to store zero
-   * values in non-existent fields.
+   * Set the element (<i>i,j</i>) to <tt>value</tt>. Throws an error if the
+   * entry does not exist or if <tt>value</tt> is not a finite number. Still,
+   * it is allowed to store zero values in non-existent fields.
    */
   void set (const unsigned int i,
             const unsigned int j,
             const number value);
 
   /**
-   * Set all elements given in a
-   * FullMatrix into the sparse matrix
-   * locations given by
-   * <tt>indices</tt>. In other words,
-   * this function writes the elements
-   * in <tt>full_matrix</tt> into the
-   * calling matrix, using the
-   * local-to-global indexing specified
-   * by <tt>indices</tt> for both the
-   * rows and the columns of the
-   * matrix. This function assumes a
-   * quadratic sparse matrix and a
-   * quadratic full_matrix, the usual
-   * situation in FE calculations.
-   *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be set anyway or
-   * they should be filtered away (and
-   * not change the previous content in
-   * the respective element if it
-   * exists). The default value is
-   * <tt>false</tt>, i.e., even zero
-   * values are treated.
+   * Set all elements given in a FullMatrix into the sparse matrix locations
+   * given by <tt>indices</tt>. In other words, this function writes the
+   * elements in <tt>full_matrix</tt> into the calling matrix, using the
+   * local-to-global indexing specified by <tt>indices</tt> for both the rows
+   * and the columns of the matrix. This function assumes a quadratic sparse
+   * matrix and a quadratic full_matrix, the usual situation in FE
+   * calculations.
+   *
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be set anyway or they should be filtered away
+   * (and not change the previous content in the respective element if it
+   * exists). The default value is <tt>false</tt>, i.e., even zero values are
+   * treated.
    */
   template <typename number2>
   void set (const std::vector<unsigned int> &indices,
@@ -857,11 +647,9 @@ public:
             const bool                       elide_zero_values = false);
 
   /**
-   * Same function as before, but now
-   * including the possibility to use
-   * rectangular full_matrices and
-   * different local-to-global indexing
-   * on rows and columns, respectively.
+   * Same function as before, but now including the possibility to use
+   * rectangular full_matrices and different local-to-global indexing on rows
+   * and columns, respectively.
    */
   template <typename number2>
   void set (const std::vector<unsigned int> &row_indices,
@@ -870,22 +658,14 @@ public:
             const bool                       elide_zero_values = false);
 
   /**
-   * Set several elements in the
-   * specified row of the matrix with
-   * column indices as given by
-   * <tt>col_indices</tt> to the
-   * respective value.
+   * Set several elements in the specified row of the matrix with column
+   * indices as given by <tt>col_indices</tt> to the respective value.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be set anyway or
-   * they should be filtered away (and
-   * not change the previous content in
-   * the respective element if it
-   * exists). The default value is
-   * <tt>false</tt>, i.e., even zero
-   * values are treated.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be set anyway or they should be filtered away
+   * (and not change the previous content in the respective element if it
+   * exists). The default value is <tt>false</tt>, i.e., even zero values are
+   * treated.
    */
   template <typename number2>
   void set (const unsigned int               row,
@@ -894,20 +674,13 @@ public:
             const bool                       elide_zero_values = false);
 
   /**
-   * Set several elements to values
-   * given by <tt>values</tt> in a
-   * given row in columns given by
-   * col_indices into the sparse
-   * matrix.
+   * Set several elements to values given by <tt>values</tt> in a given row in
+   * columns given by col_indices into the sparse matrix.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be inserted anyway
-   * or they should be filtered
-   * away. The default value is
-   * <tt>false</tt>, i.e., even zero
-   * values are inserted/replaced.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be inserted anyway or they should be filtered
+   * away. The default value is <tt>false</tt>, i.e., even zero values are
+   * inserted/replaced.
    */
   template <typename number2>
   void set (const unsigned int  row,
@@ -917,44 +690,27 @@ public:
             const bool          elide_zero_values = false);
 
   /**
-   * Add <tt>value</tt> to the
-   * element (<i>i,j</i>).  Throws
-   * an error if the entry does not
-   * exist or if <tt>value</tt> is
-   * not a finite number. Still, it
-   * is allowed to store zero
-   * values in non-existent fields.
+   * Add <tt>value</tt> to the element (<i>i,j</i>).  Throws an error if the
+   * entry does not exist or if <tt>value</tt> is not a finite number. Still,
+   * it is allowed to store zero values in non-existent fields.
    */
   void add (const unsigned int i,
             const unsigned int j,
             const number value);
 
   /**
-   * Add all elements given in a
-   * FullMatrix<double> into sparse
-   * matrix locations given by
-   * <tt>indices</tt>. In other words,
-   * this function adds the elements in
-   * <tt>full_matrix</tt> to the
-   * respective entries in calling
-   * matrix, using the local-to-global
-   * indexing specified by
-   * <tt>indices</tt> for both the rows
-   * and the columns of the
-   * matrix. This function assumes a
-   * quadratic sparse matrix and a
-   * quadratic full_matrix, the usual
-   * situation in FE calculations.
-   *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be added anyway or
-   * these should be filtered away and
-   * only non-zero data is added. The
-   * default value is <tt>true</tt>,
-   * i.e., zero values won't be added
-   * into the matrix.
+   * Add all elements given in a FullMatrix<double> into sparse matrix
+   * locations given by <tt>indices</tt>. In other words, this function adds
+   * the elements in <tt>full_matrix</tt> to the respective entries in calling
+   * matrix, using the local-to-global indexing specified by <tt>indices</tt>
+   * for both the rows and the columns of the matrix. This function assumes a
+   * quadratic sparse matrix and a quadratic full_matrix, the usual situation
+   * in FE calculations.
+   *
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be added anyway or these should be filtered
+   * away and only non-zero data is added. The default value is <tt>true</tt>,
+   * i.e., zero values won't be added into the matrix.
    */
   template <typename number2>
   void add (const std::vector<unsigned int> &indices,
@@ -962,11 +718,9 @@ public:
             const bool                       elide_zero_values = true);
 
   /**
-   * Same function as before, but now
-   * including the possibility to use
-   * rectangular full_matrices and
-   * different local-to-global indexing
-   * on rows and columns, respectively.
+   * Same function as before, but now including the possibility to use
+   * rectangular full_matrices and different local-to-global indexing on rows
+   * and columns, respectively.
    */
   template <typename number2>
   void add (const std::vector<unsigned int> &row_indices,
@@ -975,21 +729,13 @@ public:
             const bool                       elide_zero_values = true);
 
   /**
-   * Set several elements in the
-   * specified row of the matrix with
-   * column indices as given by
-   * <tt>col_indices</tt> to the
-   * respective value.
+   * Set several elements in the specified row of the matrix with column
+   * indices as given by <tt>col_indices</tt> to the respective value.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be added anyway or
-   * these should be filtered away and
-   * only non-zero data is added. The
-   * default value is <tt>true</tt>,
-   * i.e., zero values won't be added
-   * into the matrix.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be added anyway or these should be filtered
+   * away and only non-zero data is added. The default value is <tt>true</tt>,
+   * i.e., zero values won't be added into the matrix.
    */
   template <typename number2>
   void add (const unsigned int               row,
@@ -998,21 +744,13 @@ public:
             const bool                       elide_zero_values = true);
 
   /**
-   * Add an array of values given by
-   * <tt>values</tt> in the given
-   * global matrix row at columns
-   * specified by col_indices in the
-   * sparse matrix.
+   * Add an array of values given by <tt>values</tt> in the given global
+   * matrix row at columns specified by col_indices in the sparse matrix.
    *
-   * The optional parameter
-   * <tt>elide_zero_values</tt> can be
-   * used to specify whether zero
-   * values should be added anyway or
-   * these should be filtered away and
-   * only non-zero data is added. The
-   * default value is <tt>true</tt>,
-   * i.e., zero values won't be added
-   * into the matrix.
+   * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+   * whether zero values should be added anyway or these should be filtered
+   * away and only non-zero data is added. The default value is <tt>true</tt>,
+   * i.e., zero values won't be added into the matrix.
    */
   template <typename number2>
   void add (const unsigned int  row,
@@ -1023,140 +761,83 @@ public:
             const bool          col_indices_are_sorted = false);
 
   /**
-   * Multiply the entire matrix by a
-   * fixed factor.
+   * Multiply the entire matrix by a fixed factor.
    */
   SparseMatrix &operator *= (const number factor);
 
   /**
-   * Divide the entire matrix by a
-   * fixed factor.
+   * Divide the entire matrix by a fixed factor.
    */
   SparseMatrix &operator /= (const number factor);
 
   /**
-   * Symmetrize the matrix by
-   * forming the mean value between
-   * the existing matrix and its
-   * transpose, $A = \frac 12(A+A^T)$.
-   *
-   * This operation assumes that
-   * the underlying sparsity
-   * pattern represents a symmetric
-   * object. If this is not the
-   * case, then the result of this
-   * operation will not be a
-   * symmetric matrix, since it
-   * only explicitly symmetrizes
-   * by looping over the lower left
-   * triangular part for efficiency
-   * reasons; if there are entries
-   * in the upper right triangle,
-   * then these elements are missed
-   * in the
-   * symmetrization. Symmetrization
-   * of the sparsity pattern can be
-   * obtain by
-   * SparsityPattern::symmetrize().
+   * Symmetrize the matrix by forming the mean value between the existing
+   * matrix and its transpose, $A = \frac 12(A+A^T)$.
+   *
+   * This operation assumes that the underlying sparsity pattern represents a
+   * symmetric object. If this is not the case, then the result of this
+   * operation will not be a symmetric matrix, since it only explicitly
+   * symmetrizes by looping over the lower left triangular part for efficiency
+   * reasons; if there are entries in the upper right triangle, then these
+   * elements are missed in the symmetrization. Symmetrization of the sparsity
+   * pattern can be obtain by SparsityPattern::symmetrize().
    */
   void symmetrize ();
 
   /**
-   * Copy the given matrix to this
-   * one.  The operation throws an
-   * error if the sparsity patterns
-   * of the two involved matrices
-   * do not point to the same
-   * object, since in this case the
-   * copy operation is
-   * cheaper. Since this operation
-   * is notheless not for free, we
-   * do not make it available
-   * through <tt>operator =</tt>,
-   * since this may lead to
-   * unwanted usage, e.g. in copy
-   * arguments to functions, which
-   * should really be arguments by
-   * reference.
-   *
-   * The source matrix may be a matrix
-   * of arbitrary type, as long as its
-   * data type is convertible to the
-   * data type of this matrix.
-   *
-   * The function returns a reference to
-   * <tt>*this</tt>.
+   * Copy the given matrix to this one.  The operation throws an error if the
+   * sparsity patterns of the two involved matrices do not point to the same
+   * object, since in this case the copy operation is cheaper. Since this
+   * operation is notheless not for free, we do not make it available through
+   * <tt>operator =</tt>, since this may lead to unwanted usage, e.g. in copy
+   * arguments to functions, which should really be arguments by reference.
+   *
+   * The source matrix may be a matrix of arbitrary type, as long as its data
+   * type is convertible to the data type of this matrix.
+   *
+   * The function returns a reference to <tt>*this</tt>.
    */
   template <typename somenumber>
   SparseMatrix<number> &
   copy_from (const SparseMatrix<somenumber> &source);
 
   /**
-   * This function is complete
-   * analogous to the
-   * SparsityPattern::copy_from()
-   * function in that it allows to
-   * initialize a whole matrix in
-   * one step. See there for more
-   * information on argument types
-   * and their meaning. You can
-   * also find a small example on
-   * how to use this function
-   * there.
-   *
-   * The only difference to the
-   * cited function is that the
-   * objects which the inner
-   * iterator points to need to be
-   * of type <tt>std::pair<unsigned
-   * int, value</tt>, where
-   * <tt>value</tt> needs to be
-   * convertible to the element
-   * type of this class, as
-   * specified by the
-   * <tt>number</tt> template
+   * This function is complete analogous to the SparsityPattern::copy_from()
+   * function in that it allows to initialize a whole matrix in one step. See
+   * there for more information on argument types and their meaning. You can
+   * also find a small example on how to use this function there.
+   *
+   * The only difference to the cited function is that the objects which the
+   * inner iterator points to need to be of type <tt>std::pair<unsigned int,
+   * value</tt>, where <tt>value</tt> needs to be convertible to the element
+   * type of this class, as specified by the <tt>number</tt> template
    * argument.
    *
-   * Previous content of the matrix
-   * is overwritten. Note that the
-   * entries specified by the input
-   * parameters need not
-   * necessarily cover all elements
-   * of the matrix. Elements not
-   * covered remain untouched.
+   * Previous content of the matrix is overwritten. Note that the entries
+   * specified by the input parameters need not necessarily cover all elements
+   * of the matrix. Elements not covered remain untouched.
    */
   template <typename ForwardIterator>
   void copy_from (const ForwardIterator begin,
                   const ForwardIterator end);
 
   /**
-   * Copy the nonzero entries of a
-   * full matrix into this
-   * object. Previous content is
-   * deleted. Note that the
-   * underlying sparsity pattern
-   * must be appropriate to hold
-   * the nonzero entries of the
-   * full matrix.
+   * Copy the nonzero entries of a full matrix into this object. Previous
+   * content is deleted. Note that the underlying sparsity pattern must be
+   * appropriate to hold the nonzero entries of the full matrix.
    */
   template <typename somenumber>
   void copy_from (const FullMatrix<somenumber> &matrix);
 
   /**
-   * Add <tt>matrix</tt> scaled by
-   * <tt>factor</tt> to this matrix,
-   * i.e. the matrix <tt>factor*matrix</tt>
-   * is added to <tt>this</tt>. This
-   * function throws an error if the
-   * sparsity patterns of the two involved
-   * matrices do not point to the same
-   * object, since in this case the
-   * operation is cheaper.
-   *
-   * The source matrix may be a sparse
-   * matrix over an arbitrary underlying
-   * scalar type, as long as its data type
-   * is convertible to the data type of
+   * Add <tt>matrix</tt> scaled by <tt>factor</tt> to this matrix, i.e. the
+   * matrix <tt>factor*matrix</tt> is added to <tt>this</tt>. This function
+   * throws an error if the sparsity patterns of the two involved matrices do
+   * not point to the same object, since in this case the operation is
+   * cheaper.
+   *
+   * The source matrix may be a sparse matrix over an arbitrary underlying
+   * scalar type, as long as its data type is convertible to the data type of
    * this matrix.
    */
   template <typename somenumber>
@@ -1170,134 +851,84 @@ public:
 //@{
 
   /**
-   * Return the value of the entry
-   * (<i>i,j</i>).  This may be an
-   * expensive operation and you
-   * should always take care where
-   * to call this function.  In
-   * order to avoid abuse, this
-   * function throws an exception
-   * if the required element does
-   * not exist in the matrix.
-   *
-   * In case you want a function
-   * that returns zero instead (for
-   * entries that are not in the
-   * sparsity pattern of the
-   * matrix), use the el()
-   * function.
+   * Return the value of the entry (<i>i,j</i>).  This may be an expensive
+   * operation and you should always take care where to call this function.
+   * In order to avoid abuse, this function throws an exception if the
+   * required element does not exist in the matrix.
    *
-   * If you are looping over all elements,
-   * consider using one of the iterator
-   * classes instead, since they are
-   * tailored better to a sparse matrix
+   * In case you want a function that returns zero instead (for entries that
+   * are not in the sparsity pattern of the matrix), use the el() function.
+   *
+   * If you are looping over all elements, consider using one of the iterator
+   * classes instead, since they are tailored better to a sparse matrix
    * structure.
    */
   number operator () (const unsigned int i,
                       const unsigned int j) const;
 
   /**
-   * This function is mostly like
-   * operator()() in that it
-   * returns the value of the
-   * matrix entry (<i>i,j</i>). The
-   * only difference is that if
-   * this entry does not exist in
-   * the sparsity pattern, then
-   * instead of raising an
-   * exception, zero is
-   * returned. While this may be
-   * convenient in some cases, note
-   * that it is simple to write
-   * algorithms that are slow
-   * compared to an optimal
-   * solution, since the sparsity
-   * of the matrix is not used.
-   *
-   * If you are looping over all elements,
-   * consider using one of the iterator
-   * classes instead, since they are
-   * tailored better to a sparse matrix
+   * This function is mostly like operator()() in that it returns the value of
+   * the matrix entry (<i>i,j</i>). The only difference is that if this entry
+   * does not exist in the sparsity pattern, then instead of raising an
+   * exception, zero is returned. While this may be convenient in some cases,
+   * note that it is simple to write algorithms that are slow compared to an
+   * optimal solution, since the sparsity of the matrix is not used.
+   *
+   * If you are looping over all elements, consider using one of the iterator
+   * classes instead, since they are tailored better to a sparse matrix
    * structure.
    */
   number el (const unsigned int i,
              const unsigned int j) const;
 
   /**
-   * Return the main diagonal
-   * element in the <i>i</i>th
-   * row. This function throws an
-   * error if the matrix is not
-   * quadratic (see
+   * Return the main diagonal element in the <i>i</i>th row. This function
+   * throws an error if the matrix is not quadratic (see
    * SparsityPattern::optimize_diagonal()).
    *
-   * This function is considerably
-   * faster than the operator()(),
-   * since for quadratic matrices, the
-   * diagonal entry may be the
-   * first to be stored in each row
-   * and access therefore does not
-   * involve searching for the
-   * right column number.
+   * This function is considerably faster than the operator()(), since for
+   * quadratic matrices, the diagonal entry may be the first to be stored in
+   * each row and access therefore does not involve searching for the right
+   * column number.
    */
   number diag_element (const unsigned int i) const;
 
   /**
-   * Same as above, but return a
-   * writeable reference. You're
-   * sure you know what you do?
+   * Same as above, but return a writeable reference. You're sure you know
+   * what you do?
    */
   number &diag_element (const unsigned int i);
 
   /**
-   * Access to values in internal
-   * mode.  Returns the value of
-   * the <tt>index</tt>th entry in
-   * <tt>row</tt>. Here,
-   * <tt>index</tt> refers to the
-   * internal representation of the
-   * matrix, not the column. Be
-   * sure to understand what you
-   * are doing here.
+   * Access to values in internal mode.  Returns the value of the
+   * <tt>index</tt>th entry in <tt>row</tt>. Here, <tt>index</tt> refers to
+   * the internal representation of the matrix, not the column. Be sure to
+   * understand what you are doing here.
    *
-   * @deprecated Use iterator or
-   * const_iterator instead!
+   * @deprecated Use iterator or const_iterator instead!
    */
   number raw_entry (const unsigned int row,
                     const unsigned int index) const;
 
   /**
-   * This is for hackers. Get
-   * access to the <i>i</i>th element of
-   * this matrix. The elements are
-   * stored in a consecutive way,
-   * refer to the SparsityPattern
-   * class for more details.
-   *
-   * You should use this interface
-   * very carefully and only if you
-   * are absolutely sure to know
-   * what you do. You should also
-   * note that the structure of
-   * these arrays may change over
-   * time.  If you change the
-   * layout yourself, you should
-   * also rename this function to
-   * avoid programs relying on
-   * outdated information!
-   *
-   * @internal @deprecated Use iterator or
-   * const_iterator instead!
+   * This is for hackers. Get access to the <i>i</i>th element of this
+   * matrix. The elements are stored in a consecutive way, refer to the
+   * SparsityPattern class for more details.
+   *
+   * You should use this interface very carefully and only if you are
+   * absolutely sure to know what you do. You should also note that the
+   * structure of these arrays may change over time.  If you change the layout
+   * yourself, you should also rename this function to avoid programs relying
+   * on outdated information!
+   *
+   * @internal @deprecated Use iterator or const_iterator instead!
    */
   number global_entry (const unsigned int i) const;
 
   /**
-   * Same as above, but with write
-   * access.  You certainly know
-   * what you do?
+   * Same as above, but with write access.  You certainly know what you do?
    *
-   * @internal @deprecated Use iterator or
-   * const_iterator instead!
+   * @internal @deprecated Use iterator or const_iterator instead!
    */
   number &global_entry (const unsigned int i);
 
@@ -1307,167 +938,106 @@ public:
    */
 //@{
   /**
-   * Matrix-vector multiplication:
-   * let <i>dst = M*src</i> with
-   * <i>M</i> being this matrix.
+   * Matrix-vector multiplication: let <i>dst = M*src</i> with <i>M</i> being
+   * this matrix.
    *
-   * Note that while this function can
-   * operate on all vectors that offer
-   * iterator classes, it is only really
-   * effective for objects of type @ref
-   * Vector. For all classes for which
-   * iterating over elements, or random
-   * member access is expensive, this
-   * function is not efficient. In
-   * particular, if you want to multiply
-   * with BlockVector objects, you should
-   * consider using a BlockSparseMatrix as
-   * well.
-   *
-   * Source and destination must
-   * not be the same vector.
+   * Note that while this function can operate on all vectors that offer
+   * iterator classes, it is only really effective for objects of type @ref
+   * Vector. For all classes for which iterating over elements, or random
+   * member access is expensive, this function is not efficient. In
+   * particular, if you want to multiply with BlockVector objects, you should
+   * consider using a BlockSparseMatrix as well.
+   *
+   * Source and destination must not be the same vector.
    */
   template <class OutVector, class InVector>
   void vmult (OutVector &dst,
               const InVector &src) const;
 
   /**
-   * Matrix-vector multiplication:
-   * let <i>dst = M<sup>T</sup>*src</i> with
-   * <i>M</i> being this
-   * matrix. This function does the
-   * same as vmult() but takes
-   * the transposed matrix.
-   *
-   * Note that while this function can
-   * operate on all vectors that offer
-   * iterator classes, it is only really
-   * effective for objects of type @ref
-   * Vector. For all classes for which
-   * iterating over elements, or random
-   * member access is expensive, this
-   * function is not efficient. In
-   * particular, if you want to multiply
-   * with BlockVector objects, you should
-   * consider using a BlockSparseMatrix as
-   * well.
-   *
-   * Source and destination must
-   * not be the same vector.
+   * Matrix-vector multiplication: let <i>dst = M<sup>T</sup>*src</i> with
+   * <i>M</i> being this matrix. This function does the same as vmult() but
+   * takes the transposed matrix.
+   *
+   * Note that while this function can operate on all vectors that offer
+   * iterator classes, it is only really effective for objects of type @ref
+   * Vector. For all classes for which iterating over elements, or random
+   * member access is expensive, this function is not efficient. In
+   * particular, if you want to multiply with BlockVector objects, you should
+   * consider using a BlockSparseMatrix as well.
+   *
+   * Source and destination must not be the same vector.
    */
   template <class OutVector, class InVector>
   void Tvmult (OutVector &dst,
                const InVector &src) const;
 
   /**
-   * Adding Matrix-vector
-   * multiplication. Add
-   * <i>M*src</i> on <i>dst</i>
-   * with <i>M</i> being this
-   * matrix.
+   * Adding Matrix-vector multiplication. Add <i>M*src</i> on <i>dst</i> with
+   * <i>M</i> being this matrix.
+   *
+   * Note that while this function can operate on all vectors that offer
+   * iterator classes, it is only really effective for objects of type @ref
+   * Vector. For all classes for which iterating over elements, or random
+   * member access is expensive, this function is not efficient. In
+   * particular, if you want to multiply with BlockVector objects, you should
+   * consider using a BlockSparseMatrix as well.
    *
-   * Note that while this function can
-   * operate on all vectors that offer
-   * iterator classes, it is only really
-   * effective for objects of type @ref
-   * Vector. For all classes for which
-   * iterating over elements, or random
-   * member access is expensive, this
-   * function is not efficient. In
-   * particular, if you want to multiply
-   * with BlockVector objects, you should
-   * consider using a BlockSparseMatrix as
-   * well.
-   *
-   * Source and destination must
-   * not be the same vector.
+   * Source and destination must not be the same vector.
    */
   template <class OutVector, class InVector>
   void vmult_add (OutVector &dst,
                   const InVector &src) const;
 
   /**
-   * Adding Matrix-vector
-   * multiplication. Add
-   * <i>M<sup>T</sup>*src</i> to
-   * <i>dst</i> with <i>M</i> being
-   * this matrix. This function
-   * does the same as vmult_add()
-   * but takes the transposed
-   * matrix.
+   * Adding Matrix-vector multiplication. Add <i>M<sup>T</sup>*src</i> to
+   * <i>dst</i> with <i>M</i> being this matrix. This function does the same
+   * as vmult_add() but takes the transposed matrix.
+   *
+   * Note that while this function can operate on all vectors that offer
+   * iterator classes, it is only really effective for objects of type @ref
+   * Vector. For all classes for which iterating over elements, or random
+   * member access is expensive, this function is not efficient. In
+   * particular, if you want to multiply with BlockVector objects, you should
+   * consider using a BlockSparseMatrix as well.
    *
-   * Note that while this function can
-   * operate on all vectors that offer
-   * iterator classes, it is only really
-   * effective for objects of type @ref
-   * Vector. For all classes for which
-   * iterating over elements, or random
-   * member access is expensive, this
-   * function is not efficient. In
-   * particular, if you want to multiply
-   * with BlockVector objects, you should
-   * consider using a BlockSparseMatrix as
-   * well.
-   *
-   * Source and destination must
-   * not be the same vector.
+   * Source and destination must not be the same vector.
    */
   template <class OutVector, class InVector>
   void Tvmult_add (OutVector &dst,
                    const InVector &src) const;
 
   /**
-   * Return the square of the norm
-   * of the vector $v$ with respect
-   * to the norm induced by this
-   * matrix,
-   * i.e. $\left(v,Mv\right)$. This
-   * is useful, e.g. in the finite
-   * element context, where the
-   * $L_2$ norm of a function
-   * equals the matrix norm with
-   * respect to the mass matrix of
-   * the vector representing the
-   * nodal values of the finite
-   * element function.
-   *
-   * Obviously, the matrix needs to be
-   * quadratic for this operation, and for
-   * the result to actually be a norm it
-   * also needs to be either real symmetric
-   * or complex hermitian.
-   *
-   * The underlying template types of both
-   * this matrix and the given vector
-   * should either both be real or
-   * complex-valued, but not mixed, for
-   * this function to make sense.
+   * Return the square of the norm of the vector $v$ with respect to the norm
+   * induced by this matrix, i.e. $\left(v,Mv\right)$. This is useful, e.g. in
+   * the finite element context, where the $L_2$ norm of a function equals the
+   * matrix norm with respect to the mass matrix of the vector representing
+   * the nodal values of the finite element function.
+   *
+   * Obviously, the matrix needs to be quadratic for this operation, and for
+   * the result to actually be a norm it also needs to be either real
+   * symmetric or complex hermitian.
+   *
+   * The underlying template types of both this matrix and the given vector
+   * should either both be real or complex-valued, but not mixed, for this
+   * function to make sense.
    */
   template <typename somenumber>
   somenumber matrix_norm_square (const Vector<somenumber> &v) const;
 
   /**
-   * Compute the matrix scalar
-   * product $\left(u,Mv\right)$.
+   * Compute the matrix scalar product $\left(u,Mv\right)$.
    */
   template <typename somenumber>
   somenumber matrix_scalar_product (const Vector<somenumber> &u,
                                     const Vector<somenumber> &v) const;
 
   /**
-   * Compute the residual of an
-   * equation <i>Mx=b</i>, where
-   * the residual is defined to be
-   * <i>r=b-Mx</i>. Write the
-   * residual into
-   * <tt>dst</tt>. The
-   * <i>l<sub>2</sub></i> norm of
-   * the residual vector is
-   * returned.
+   * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+   * defined to be <i>r=b-Mx</i>. Write the residual into <tt>dst</tt>. The
+   * <i>l<sub>2</sub></i> norm of the residual vector is returned.
    *
-   * Source <i>x</i> and destination
-   * <i>dst</i> must not be the same
-   * vector.
+   * Source <i>x</i> and destination <i>dst</i> must not be the same vector.
    */
   template <typename somenumber>
   somenumber residual (Vector<somenumber>       &dst,
@@ -1475,44 +1045,27 @@ public:
                        const Vector<somenumber> &b) const;
 
   /**
-   * Perform the matrix-matrix
-   * multiplication <tt>C = A * B</tt>,
-   * or, if an optional vector argument
-   * is given, <tt>C = A * diag(V) *
-   * B</tt>, where <tt>diag(V)</tt>
-   * defines a diagonal matrix with the
-   * vector entries.
-   *
-   * This function assumes that the
-   * calling matrix <tt>A</tt> and
-   * <tt>B</tt> have compatible
-   * sizes. The size of <tt>C</tt> will
-   * be set within this function.
-   *
-   * The content as well as the sparsity
-   * pattern of the matrix C will be
-   * changed by this function, so make
-   * sure that the sparsity pattern is
-   * not used somewhere else in your
-   * program. This is an expensive
-   * operation, so think twice before you
-   * use this function.
-   *
-   * There is an optional flag
-   * <tt>rebuild_sparsity_pattern</tt>
-   * that can be used to bypass the
-   * creation of a new sparsity pattern
-   * and instead uses the sparsity
-   * pattern stored in <tt>C</tt>. In
-   * that case, make sure that it really
-   * fits. The default is to rebuild the
-   * sparsity pattern.
-   *
-   * @note Rebuilding the sparsity pattern
-   * requires changing it. This means that
-   * all other matrices that are associated
-   * with this sparsity pattern will
-   * then have invalid entries.
+   * Perform the matrix-matrix multiplication <tt>C = A * B</tt>, or, if an
+   * optional vector argument is given, <tt>C = A * diag(V) * B</tt>, where
+   * <tt>diag(V)</tt> defines a diagonal matrix with the vector entries.
+   *
+   * This function assumes that the calling matrix <tt>A</tt> and <tt>B</tt>
+   * have compatible sizes. The size of <tt>C</tt> will be set within this
+   * function.
+   *
+   * The content as well as the sparsity pattern of the matrix C will be
+   * changed by this function, so make sure that the sparsity pattern is not
+   * used somewhere else in your program. This is an expensive operation, so
+   * think twice before you use this function.
+   *
+   * There is an optional flag <tt>rebuild_sparsity_pattern</tt> that can be
+   * used to bypass the creation of a new sparsity pattern and instead uses
+   * the sparsity pattern stored in <tt>C</tt>. In that case, make sure that
+   * it really fits. The default is to rebuild the sparsity pattern.
+   *
+   * @note Rebuilding the sparsity pattern requires changing it. This means
+   * that all other matrices that are associated with this sparsity pattern
+   * will then have invalid entries.
    */
   template <typename numberB, typename numberC>
   void mmult (SparseMatrix<numberC>       &C,
@@ -1521,46 +1074,28 @@ public:
               const bool                   rebuild_sparsity_pattern = true) const;
 
   /**
-   * Perform the matrix-matrix
-   * multiplication with the transpose of
-   * <tt>this</tt>, i.e., <tt>C =
-   * A<sup>T</sup> * B</tt>, or, if an
-   * optional vector argument is given,
-   * <tt>C = A<sup>T</sup> * diag(V) *
-   * B</tt>, where <tt>diag(V)</tt>
-   * defines a diagonal matrix with the
-   * vector entries.
-   *
-   * This function assumes that the
-   * calling matrix <tt>A</tt> and
-   * <tt>B</tt> have compatible
-   * sizes. The size of <tt>C</tt> will
-   * be set within this function.
-   *
-   * The content as well as the sparsity
-   * pattern of the matrix C will be
-   * changed by this function, so make
-   * sure that the sparsity pattern is
-   * not used somewhere else in your
-   * program. This is an expensive
-   * operation, so think twice before you
-   * use this function.
-   *
-   * There is an optional flag
-   * <tt>rebuild_sparsity_pattern</tt>
-   * that can be used to bypass the
-   * creation of a new sparsity pattern
-   * and instead uses the sparsity
-   * pattern stored in <tt>C</tt>. In
-   * that case, make sure that it really
-   * fits. The default is to rebuild the
-   * sparsity pattern.
-   *
-   * @note Rebuilding the sparsity pattern
-   * requires changing it. This means that
-   * all other matrices that are associated
-   * with this sparsity pattern will
-   * then have invalid entries.
+   * Perform the matrix-matrix multiplication with the transpose of
+   * <tt>this</tt>, i.e., <tt>C = A<sup>T</sup> * B</tt>, or, if an optional
+   * vector argument is given, <tt>C = A<sup>T</sup> * diag(V) * B</tt>, where
+   * <tt>diag(V)</tt> defines a diagonal matrix with the vector entries.
+   *
+   * This function assumes that the calling matrix <tt>A</tt> and <tt>B</tt>
+   * have compatible sizes. The size of <tt>C</tt> will be set within this
+   * function.
+   *
+   * The content as well as the sparsity pattern of the matrix C will be
+   * changed by this function, so make sure that the sparsity pattern is not
+   * used somewhere else in your program. This is an expensive operation, so
+   * think twice before you use this function.
+   *
+   * There is an optional flag <tt>rebuild_sparsity_pattern</tt> that can be
+   * used to bypass the creation of a new sparsity pattern and instead uses
+   * the sparsity pattern stored in <tt>C</tt>. In that case, make sure that
+   * it really fits. The default is to rebuild the sparsity pattern.
+   *
+   * @note Rebuilding the sparsity pattern requires changing it. This means
+   * that all other matrices that are associated with this sparsity pattern
+   * will then have invalid entries.
    */
   template <typename numberB, typename numberC>
   void Tmmult (SparseMatrix<numberC>       &C,
@@ -1575,39 +1110,27 @@ public:
 //@{
 
   /**
-   * Return the $l_1$-norm of the matrix,
-   * that is $|M|_1=\max_{\mathrm{all\
-   * columns\ }j}\sum_{\mathrm{all\ rows\
-   * } i} |M_{ij}|$, (max. sum of
-   * columns).  This is the natural
-   * matrix norm that is compatible to
-   * the $l_1$-norm for vectors, i.e.
-   * $|Mv|_1\leq |M|_1 |v|_1$.
-   * (cf. Haemmerlin-Hoffmann :
-   * Numerische Mathematik)
+   * Return the $l_1$-norm of the matrix, that is $|M|_1=\max_{\mathrm{all\
+   * columns\ }j}\sum_{\mathrm{all\ rows\ } i} |M_{ij}|$, (max. sum of
+   * columns).  This is the natural matrix norm that is compatible to the
+   * $l_1$-norm for vectors, i.e.  $|Mv|_1\leq |M|_1 |v|_1$.
+   * (cf. Haemmerlin-Hoffmann: Numerische Mathematik)
    */
   real_type l1_norm () const;
 
   /**
-   * Return the $l_\infty$-norm of the
-   * matrix, that is
-   * $|M|_\infty=\max_{\mathrm{all\ rows\
-   * }i}\sum_{\mathrm{all\ columns\ }j}
-   * |M_{ij}|$, (max. sum of rows).  This
-   * is the natural matrix norm that is
-   * compatible to the $l_\infty$-norm of
-   * vectors, i.e.  $|Mv|_\infty \leq
-   * |M|_\infty |v|_\infty$.
-   * (cf. Haemmerlin-Hoffmann :
-   * Numerische Mathematik)
+   * Return the $l_\infty$-norm of the matrix, that is
+   * $|M|_\infty=\max_{\mathrm{all\ rows\ }i}\sum_{\mathrm{all\ columns\ }j}
+   * |M_{ij}|$, (max. sum of rows).  This is the natural matrix norm that is
+   * compatible to the $l_\infty$-norm of vectors, i.e.  $|Mv|_\infty \leq
+   * |M|_\infty |v|_\infty$.  (cf. Haemmerlin-Hoffmann: Numerische
+   * Mathematik)
    */
   real_type linfty_norm () const;
 
   /**
-   * Return the frobenius norm of the
-   * matrix, i.e. the square root of the
-   * sum of squares of all entries in the
-   * matrix.
+   * Return the frobenius norm of the matrix, i.e. the square root of the sum
+   * of squares of all entries in the matrix.
    */
   real_type frobenius_norm () const;
 //@}
@@ -1617,14 +1140,9 @@ public:
 //@{
 
   /**
-   * Apply the Jacobi
-   * preconditioner, which
-   * multiplies every element of
-   * the <tt>src</tt> vector by the
-   * inverse of the respective
-   * diagonal element and
-   * multiplies the result with the
-   * relaxation factor <tt>omega</tt>.
+   * Apply the Jacobi preconditioner, which multiplies every element of the
+   * <tt>src</tt> vector by the inverse of the respective diagonal element and
+   * multiplies the result with the relaxation factor <tt>omega</tt>.
    */
   template <typename somenumber>
   void precondition_Jacobi (Vector<somenumber>       &dst,
@@ -1632,15 +1150,10 @@ public:
                             const number              omega = 1.) const;
 
   /**
-   * Apply SSOR preconditioning to
-   * <tt>src</tt> with damping
-   * <tt>omega</tt>. The optional
-   * argument
-   * <tt>pos_right_of_diagonal</tt> is
-   * supposed to provide an array where
-   * each entry specifies the position
-   * just right of the diagonal in the
-   * global array of nonzeros.
+   * Apply SSOR preconditioning to <tt>src</tt> with damping
+   * <tt>omega</tt>. The optional argument <tt>pos_right_of_diagonal</tt> is
+   * supposed to provide an array where each entry specifies the position just
+   * right of the diagonal in the global array of nonzeros.
    */
   template <typename somenumber>
   void precondition_SSOR (Vector<somenumber>             &dst,
@@ -1649,8 +1162,7 @@ public:
                           const std::vector<unsigned int> &pos_right_of_diagonal=std::vector<unsigned int>()) const;
 
   /**
-   * Apply SOR preconditioning
-   * matrix to <tt>src</tt>.
+   * Apply SOR preconditioning matrix to <tt>src</tt>.
    */
   template <typename somenumber>
   void precondition_SOR (Vector<somenumber>       &dst,
@@ -1658,9 +1170,7 @@ public:
                          const number              om = 1.) const;
 
   /**
-   * Apply transpose SOR
-   * preconditioning matrix to
-   * <tt>src</tt>.
+   * Apply transpose SOR preconditioning matrix to <tt>src</tt>.
    */
   template <typename somenumber>
   void precondition_TSOR (Vector<somenumber>       &dst,
@@ -1668,11 +1178,8 @@ public:
                           const number              om = 1.) const;
 
   /**
-   * Perform SSOR preconditioning
-   * in-place.  Apply the
-   * preconditioner matrix without
-   * copying to a second vector.
-   * <tt>omega</tt> is the relaxation
+   * Perform SSOR preconditioning in-place.  Apply the preconditioner matrix
+   * without copying to a second vector.  <tt>omega</tt> is the relaxation
    * parameter.
    */
   template <typename somenumber>
@@ -1680,18 +1187,15 @@ public:
              const number        omega = 1.) const;
 
   /**
-   * Perform an SOR preconditioning
-   * in-place.  <tt>omega</tt> is
-   * the relaxation parameter.
+   * Perform an SOR preconditioning in-place.  <tt>omega</tt> is the
+   * relaxation parameter.
    */
   template <typename somenumber>
   void SOR (Vector<somenumber> &v,
             const number        om = 1.) const;
 
   /**
-   * Perform a transpose SOR
-   * preconditioning in-place.
-   * <tt>omega</tt> is the
+   * Perform a transpose SOR preconditioning in-place.  <tt>omega</tt> is the
    * relaxation parameter.
    */
   template <typename somenumber>
@@ -1699,21 +1203,14 @@ public:
              const number        om = 1.) const;
 
   /**
-   * Perform a permuted SOR
-   * preconditioning in-place.
+   * Perform a permuted SOR preconditioning in-place.
    *
-   * The standard SOR method is
-   * applied in the order
-   * prescribed by <tt>permutation</tt>,
-   * that is, first the row
-   * <tt>permutation[0]</tt>, then
-   * <tt>permutation[1]</tt> and so
-   * on. For efficiency reasons,
-   * the permutation as well as its
-   * inverse are required.
+   * The standard SOR method is applied in the order prescribed by
+   * <tt>permutation</tt>, that is, first the row <tt>permutation[0]</tt>,
+   * then <tt>permutation[1]</tt> and so on. For efficiency reasons, the
+   * permutation as well as its inverse are required.
    *
-   * <tt>omega</tt> is the
-   * relaxation parameter.
+   * <tt>omega</tt> is the relaxation parameter.
    */
   template <typename somenumber>
   void PSOR (Vector<somenumber> &v,
@@ -1722,24 +1219,14 @@ public:
              const number        om = 1.) const;
 
   /**
-   * Perform a transposed permuted SOR
-   * preconditioning in-place.
+   * Perform a transposed permuted SOR preconditioning in-place.
    *
-   * The transposed SOR method is
-   * applied in the order
-   * prescribed by
-   * <tt>permutation</tt>, that is,
-   * first the row
-   * <tt>permutation[m()-1]</tt>,
-   * then
-   * <tt>permutation[m()-2]</tt>
-   * and so on. For efficiency
-   * reasons, the permutation as
-   * well as its inverse are
-   * required.
+   * The transposed SOR method is applied in the order prescribed by
+   * <tt>permutation</tt>, that is, first the row <tt>permutation[m()-1]</tt>,
+   * then <tt>permutation[m()-2]</tt> and so on. For efficiency reasons, the
+   * permutation as well as its inverse are required.
    *
-   * <tt>omega</tt> is the
-   * relaxation parameter.
+   * <tt>omega</tt> is the relaxation parameter.
    */
   template <typename somenumber>
   void TPSOR (Vector<somenumber> &v,
@@ -1748,13 +1235,9 @@ public:
               const number        om = 1.) const;
 
   /**
-   * Do one Jacobi step on
-   * <tt>v</tt>.  Performs a direct
-   * Jacobi step with right hand
-   * side <tt>b</tt>. This function
-   * will need an auxiliary vector,
-   * which is acquired from
-   * GrowingVectorMemory.
+   * Do one Jacobi step on <tt>v</tt>.  Performs a direct Jacobi step with
+   * right hand side <tt>b</tt>. This function will need an auxiliary vector,
+   * which is acquired from GrowingVectorMemory.
    */
   template <typename somenumber>
   void Jacobi_step (Vector<somenumber> &v,
@@ -1762,10 +1245,8 @@ public:
                     const number        om = 1.) const;
 
   /**
-   * Do one SOR step on <tt>v</tt>.
-   * Performs a direct SOR step
-   * with right hand side
-   * <tt>b</tt>.
+   * Do one SOR step on <tt>v</tt>.  Performs a direct SOR step with right
+   * hand side <tt>b</tt>.
    */
   template <typename somenumber>
   void SOR_step (Vector<somenumber> &v,
@@ -1773,10 +1254,8 @@ public:
                  const number        om = 1.) const;
 
   /**
-   * Do one adjoint SOR step on
-   * <tt>v</tt>.  Performs a direct
-   * TSOR step with right hand side
-   * <tt>b</tt>.
+   * Do one adjoint SOR step on <tt>v</tt>.  Performs a direct TSOR step with
+   * right hand side <tt>b</tt>.
    */
   template <typename somenumber>
   void TSOR_step (Vector<somenumber> &v,
@@ -1784,11 +1263,8 @@ public:
                   const number        om = 1.) const;
 
   /**
-   * Do one SSOR step on
-   * <tt>v</tt>.  Performs a direct
-   * SSOR step with right hand side
-   * <tt>b</tt> by performing TSOR
-   * after SOR.
+   * Do one SSOR step on <tt>v</tt>.  Performs a direct SSOR step with right
+   * hand side <tt>b</tt> by performing TSOR after SOR.
    */
   template <typename somenumber>
   void SSOR_step (Vector<somenumber> &v,
@@ -1801,86 +1277,68 @@ public:
 //@{
 
   /**
-   * STL-like iterator with the first entry
-   * of the matrix. This is the version for
-   * constant matrices.
+   * STL-like iterator with the first entry of the matrix. This is the version
+   * for constant matrices.
    */
   const_iterator begin () const;
 
   /**
-   * Final iterator. This is the version for
-   * constant matrices.
+   * Final iterator. This is the version for constant matrices.
    */
   const_iterator end () const;
 
   /**
-   * STL-like iterator with the first entry
-   * of the matrix. This is the version for
-   * non-constant matrices.
+   * STL-like iterator with the first entry of the matrix. This is the version
+   * for non-constant matrices.
    */
   iterator begin ();
 
   /**
-   * Final iterator. This is the version for
-   * non-constant matrices.
+   * Final iterator. This is the version for non-constant matrices.
    */
   iterator end ();
 
   /**
-   * STL-like iterator with the first entry
-   * of row <tt>r</tt>. This is the version
-   * for constant matrices.
+   * STL-like iterator with the first entry of row <tt>r</tt>. This is the
+   * version for constant matrices.
    *
-   * Note that if the given row is empty,
-   * i.e. does not contain any nonzero
-   * entries, then the iterator returned by
-   * this function equals
-   * <tt>end(r)</tt>. Note also that the
-   * iterator may not be dereferencable in
+   * Note that if the given row is empty, i.e. does not contain any nonzero
+   * entries, then the iterator returned by this function equals
+   * <tt>end(r)</tt>. Note also that the iterator may not be dereferencable in
    * that case.
    */
   const_iterator begin (const unsigned int r) const;
 
   /**
-   * Final iterator of row <tt>r</tt>. It
-   * points to the first element past the
-   * end of line @p r, or past the end of
-   * the entire sparsity pattern. This is
+   * Final iterator of row <tt>r</tt>. It points to the first element past the
+   * end of line @p r, or past the end of the entire sparsity pattern. This is
    * the version for constant matrices.
    *
-   * Note that the end iterator is not
-   * necessarily dereferencable. This is in
-   * particular the case if it is the end
-   * iterator for the last row of a matrix.
+   * Note that the end iterator is not necessarily dereferencable. This is in
+   * particular the case if it is the end iterator for the last row of a
+   * matrix.
    */
   const_iterator end (const unsigned int r) const;
 
   /**
-   * STL-like iterator with the first entry
-   * of row <tt>r</tt>. This is the version
-   * for non-constant matrices.
+   * STL-like iterator with the first entry of row <tt>r</tt>. This is the
+   * version for non-constant matrices.
    *
-   * Note that if the given row is empty,
-   * i.e. does not contain any nonzero
-   * entries, then the iterator returned by
-   * this function equals
-   * <tt>end(r)</tt>. Note also that the
-   * iterator may not be dereferencable in
+   * Note that if the given row is empty, i.e. does not contain any nonzero
+   * entries, then the iterator returned by this function equals
+   * <tt>end(r)</tt>. Note also that the iterator may not be dereferencable in
    * that case.
    */
   iterator begin (const unsigned int r);
 
   /**
-   * Final iterator of row <tt>r</tt>. It
-   * points to the first element past the
-   * end of line @p r, or past the end of
-   * the entire sparsity pattern. This is
+   * Final iterator of row <tt>r</tt>. It points to the first element past the
+   * end of line @p r, or past the end of the entire sparsity pattern. This is
    * the version for non-constant matrices.
    *
-   * Note that the end iterator is not
-   * necessarily dereferencable. This is in
-   * particular the case if it is the end
-   * iterator for the last row of a matrix.
+   * Note that the end iterator is not necessarily dereferencable. This is in
+   * particular the case if it is the end iterator for the last row of a
+   * matrix.
    */
   iterator end (const unsigned int r);
 //@}
@@ -1890,58 +1348,33 @@ public:
 //@{
 
   /**
-   * Print the matrix to the given
-   * stream, using the format
-   * <tt>(row,column) value</tt>,
-   * i.e. one nonzero entry of the
-   * matrix per line. If @p across
-   * is true, print all entries on
-   * a single line, using the
-   * format row,column:value
+   * Print the matrix to the given stream, using the format <tt>(row,column)
+   * value</tt>, i.e. one nonzero entry of the matrix per line. If @p across
+   * is true, print all entries on a single line, using the format
+   * row,column:value
    */
   template <class STREAM>
   void print (STREAM &out, bool across=false) const;
 
   /**
-   * Print the matrix in the usual
-   * format, i.e. as a matrix and
-   * not as a list of nonzero
-   * elements. For better
-   * readability, elements not in
-   * the matrix are displayed as
-   * empty space, while matrix
-   * elements which are explicitly
-   * set to zero are displayed as
-   * such.
-   *
-   * The parameters allow for a
-   * flexible setting of the output
-   * format: <tt>precision</tt> and
-   * <tt>scientific</tt> are used
-   * to determine the number
-   * format, where <tt>scientific =
-   * false</tt> means fixed point
-   * notation.  A zero entry for
-   * <tt>width</tt> makes the
-   * function compute a width, but
-   * it may be changed to a
-   * positive value, if output is
-   * crude.
-   *
-   * Additionally, a character for
-   * an empty value may be
-   * specified.
-   *
-   * Finally, the whole matrix can
-   * be multiplied with a common
-   * denominator to produce more
-   * readable output, even
-   * integers.
-   *
-   * @attention This function may
-   * produce <b>large</b> amounts
-   * of output if applied to a
-   * large matrix!
+   * Print the matrix in the usual format, i.e. as a matrix and not as a list
+   * of nonzero elements. For better readability, elements not in the matrix
+   * are displayed as empty space, while matrix elements which are explicitly
+   * set to zero are displayed as such.
+   *
+   * The parameters allow for a flexible setting of the output format:
+   * <tt>precision</tt> and <tt>scientific</tt> are used to determine the
+   * number format, where <tt>scientific = false</tt> means fixed point
+   * notation.  A zero entry for <tt>width</tt> makes the function compute a
+   * width, but it may be changed to a positive value, if output is crude.
+   *
+   * Additionally, a character for an empty value may be specified.
+   *
+   * Finally, the whole matrix can be multiplied with a common denominator to
+   * produce more readable output, even integers.
+   *
+   * @attention This function may produce <b>large</b> amounts of output if
+   * applied to a large matrix!
    */
   void print_formatted (std::ostream       &out,
                         const unsigned int  precision   = 3,
@@ -1951,69 +1384,40 @@ public:
                         const double        denominator = 1.) const;
 
   /**
-   * Print the actual pattern of
-   * the matrix. For each entry
-   * with an absolute value larger
-   * than threshold, a '*' is
-   * printed, a ':' for every value
-   * smaller and a '.' for every
-   * entry not allocated.
+   * Print the actual pattern of the matrix. For each entry with an absolute
+   * value larger than threshold, a '*' is printed, a ':' for every value
+   * smaller and a '.' for every entry not allocated.
    */
   void print_pattern(std::ostream &out,
                      const double threshold = 0.) const;
 
   /**
-   * Write the data of this object
-   * en bloc to a file. This is
-   * done in a binary mode, so the
-   * output is neither readable by
-   * humans nor (probably) by other
-   * computers using a different
-   * operating system of number
-   * format.
-   *
-   * The purpose of this function
-   * is that you can swap out
-   * matrices and sparsity pattern
-   * if you are short of memory,
-   * want to communicate between
-   * different programs, or allow
-   * objects to be persistent
-   * across different runs of the
-   * program.
+   * Write the data of this object en bloc to a file. This is done in a binary
+   * mode, so the output is neither readable by humans nor (probably) by other
+   * computers using a different operating system of number format.
+   *
+   * The purpose of this function is that you can swap out matrices and
+   * sparsity pattern if you are short of memory, want to communicate between
+   * different programs, or allow objects to be persistent across different
+   * runs of the program.
    */
   void block_write (std::ostream &out) const;
 
   /**
-   * Read data that has previously
-   * been written by block_write()
-   * from a file. This is done
-   * using the inverse operations
-   * to the above function, so it
-   * is reasonably fast because the
-   * bitstream is not interpreted
-   * except for a few numbers up
-   * front.
-   *
-   * The object is resized on this
-   * operation, and all previous
-   * contents are lost. Note,
-   * however, that no checks are
-   * performed whether new data and
-   * the underlying SparsityPattern
-   * object fit together. It is
-   * your responsibility to make
-   * sure that the sparsity pattern
-   * and the data to be read match.
-   *
-   * A primitive form of error
-   * checking is performed which
-   * will recognize the bluntest
-   * attempts to interpret some
-   * data as a matrix stored
-   * bitwise to a file that wasn't
-   * actually created that way, but
-   * not more.
+   * Read data that has previously been written by block_write() from a
+   * file. This is done using the inverse operations to the above function, so
+   * it is reasonably fast because the bitstream is not interpreted except for
+   * a few numbers up front.
+   *
+   * The object is resized on this operation, and all previous contents are
+   * lost. Note, however, that no checks are performed whether new data and
+   * the underlying SparsityPattern object fit together. It is your
+   * responsibility to make sure that the sparsity pattern and the data to be
+   * read match.
+   *
+   * A primitive form of error checking is performed which will recognize the
+   * bluntest attempts to interpret some data as a matrix stored bitwise to a
+   * file that wasn't actually created that way, but not more.
    */
   void block_read (std::istream &in);
   //@}
@@ -2052,87 +1456,54 @@ public:
 
 protected:
   /**
-   * For some matrix storage
-   * formats, in particular for the
-   * PETSc distributed blockmatrices,
-   * set and add operations on
-   * individual elements can not be
-   * freely mixed. Rather, one has
-   * to synchronize operations when
-   * one wants to switch from
-   * setting elements to adding to
-   * elements.
-   * BlockMatrixBase automatically
-   * synchronizes the access by
-   * calling this helper function
-   * for each block.
-   * This function ensures that the
-   * matrix is in a state that
-   * allows adding elements; if it
-   * previously already was in this
-   * state, the function does
-   * nothing.
+   * For some matrix storage formats, in particular for the PETSc distributed
+   * blockmatrices, set and add operations on individual elements can not be
+   * freely mixed. Rather, one has to synchronize operations when one wants to
+   * switch from setting elements to adding to elements.  BlockMatrixBase
+   * automatically synchronizes the access by calling this helper function for
+   * each block.  This function ensures that the matrix is in a state that
+   * allows adding elements; if it previously already was in this state, the
+   * function does nothing.
    */
   void prepare_add();
 
   /**
-   * Same as prepare_add() but
-   * prepare the matrix for setting
-   * elements if the representation
-   * of elements in this class
-   * requires such an operation.
+   * Same as prepare_add() but prepare the matrix for setting elements if the
+   * representation of elements in this class requires such an operation.
    */
   void prepare_set();
 
 private:
   /**
-   * Pointer to the sparsity
-   * pattern used for this
-   * matrix. In order to guarantee
-   * that it is not deleted while
-   * still in use, we subscribe to
-   * it using the SmartPointer
-   * class.
+   * Pointer to the sparsity pattern used for this matrix. In order to
+   * guarantee that it is not deleted while still in use, we subscribe to it
+   * using the SmartPointer class.
    */
   SmartPointer<const SparsityPattern,SparseMatrix<number> > cols;
 
   /**
-   * Array of values for all the
-   * nonzero entries. The position
-   * within the matrix, i.e.  the
-   * row and column number for a
-   * given entry can only be
-   * deduced using the sparsity
-   * pattern. The same holds for
-   * the more common operation of
-   * finding an entry by its
-   * coordinates.
+   * Array of values for all the nonzero entries. The position within the
+   * matrix, i.e.  the row and column number for a given entry can only be
+   * deduced using the sparsity pattern. The same holds for the more common
+   * operation of finding an entry by its coordinates.
    */
   number *val;
 
   /**
-   * Allocated size of #val. This
-   * can be larger than the
-   * actually used part if the size
-   * of the matrix was reduced
-   * somewhen in the past by
-   * associating a sparsity pattern
-   * with a smaller size to this
-   * object, using the reinit()
+   * Allocated size of #val. This can be larger than the actually used part if
+   * the size of the matrix was reduced somewhen in the past by associating a
+   * sparsity pattern with a smaller size to this object, using the reinit()
    * function.
    */
   std::size_t max_len;
 
-  // make all other sparse matrices
-  // friends
+  // make all other sparse matrices friends
   template <typename somenumber> friend class SparseMatrix;
   template <typename somenumber> friend class SparseLUDecomposition;
   template <typename> friend class SparseILU;
 
   /**
-   * To allow it calling private
-   * prepare_add() and
-   * prepare_set().
+   * To allow it calling private prepare_add() and prepare_set().
    */
   template <typename> friend class BlockMatrixBase;
 };
@@ -2164,9 +1535,7 @@ unsigned int SparseMatrix<number>::n () const
 }
 
 
-// Inline the set() and add()
-// functions, since they will be
-// called frequently.
+// Inline the set() and add() functions, since they will be called frequently.
 template <typename number>
 inline
 void
@@ -2178,10 +1547,8 @@ SparseMatrix<number>::set (const unsigned int i,
 
   const unsigned int index = cols->operator()(i, j);
 
-  // it is allowed to set elements of
-  // the matrix that are not part of
-  // the sparsity pattern, if the
-  // value to which we set it is zero
+  // it is allowed to set elements of the matrix that are not part of the
+  // sparsity pattern, if the value to which we set it is zero
   if (index == SparsityPattern::invalid_entry)
     {
       Assert ((index != SparsityPattern::invalid_entry) ||
@@ -2267,10 +1634,8 @@ SparseMatrix<number>::add (const unsigned int i,
 
   const unsigned int index = cols->operator()(i, j);
 
-  // it is allowed to add elements to
-  // the matrix that are not part of
-  // the sparsity pattern, if the
-  // value to which we set it is zero
+  // it is allowed to add elements to the matrix that are not part of the
+  // sparsity pattern, if the value to which we set it is zero
   if (index == SparsityPattern::invalid_entry)
     {
       Assert ((index != SparsityPattern::invalid_entry) ||
@@ -2420,8 +1785,7 @@ number SparseMatrix<number>::diag_element (const unsigned int i) const
   Assert (cols->optimize_diagonal(),  ExcNotQuadratic());
   Assert (i<m(), ExcInvalidIndex1(i));
 
-  // Use that the first element in each
-  // row of a quadratic matrix is the main
+  // Use that the first element in each row of a quadratic matrix is the main
   // diagonal
   return val[cols->rowstart[i]];
 }
@@ -2436,8 +1800,7 @@ number &SparseMatrix<number>::diag_element (const unsigned int i)
   Assert (cols->optimize_diagonal(),  ExcNotQuadratic());
   Assert (i<m(), ExcInvalidIndex1(i));
 
-  // Use that the first element in each
-  // row of a quadratic matrix is the main
+  // Use that the first element in each row of a quadratic matrix is the main
   // diagonal
   return val[cols->rowstart[i]];
 }
@@ -2494,9 +1857,8 @@ SparseMatrix<number>::copy_from (const ForwardIterator begin,
   Assert (static_cast<unsigned int>(std::distance (begin, end)) == m(),
           ExcIteratorRange (std::distance (begin, end), m()));
 
-  // for use in the inner loop, we
-  // define a typedef to the type of
-  // the inner iterators
+  // for use in the inner loop, we define a typedef to the type of the inner
+  // iterators
   typedef typename std::iterator_traits<ForwardIterator>::value_type::const_iterator inner_iterator;
   unsigned int row=0;
   for (ForwardIterator i=begin; i!=end; ++i, ++row)
@@ -2822,14 +2184,12 @@ inline
 typename SparseMatrix<number>::const_iterator
 SparseMatrix<number>::begin () const
 {
-  // search for the first line with a nonzero
-  // number of entries
+  // search for the first line with a nonzero number of entries
   for (unsigned int r=0; r<m(); ++r)
     if (cols->row_length(r) > 0)
       return const_iterator(this, r, 0);
 
-  // alright, this matrix is completely
-  // empty. that's strange but ok. simply
+  // alright, this matrix is completely empty. that's strange but ok. simply
   // return the end() iterator
   return end();
 }
@@ -2849,14 +2209,12 @@ inline
 typename SparseMatrix<number>::iterator
 SparseMatrix<number>::begin ()
 {
-  // search for the first line with a nonzero
-  // number of entries
+  // search for the first line with a nonzero number of entries
   for (unsigned int r=0; r<m(); ++r)
     if (cols->row_length(r) > 0)
       return iterator(this, r, 0);
 
-  // alright, this matrix is completely
-  // empty. that's strange but ok. simply
+  // alright, this matrix is completely empty. that's strange but ok. simply
   // return the end() iterator
   return end();
 }
@@ -2893,15 +2251,13 @@ SparseMatrix<number>::end (const unsigned int r) const
 {
   Assert (r<m(), ExcIndexRange(r,0,m()));
 
-  // place the iterator on the first entry
-  // past this line, or at the end of the
-  // matrix
+  // place the iterator on the first entry past this line, or at the end of
+  // the matrix
   for (unsigned int i=r+1; i<m(); ++i)
     if (cols->row_length(i) > 0)
       return const_iterator(this, i, 0);
 
-  // if there is no such line, then take the
-  // end iterator of the matrix
+  // if there is no such line, then take the end iterator of the matrix
   return end();
 }
 
@@ -2929,15 +2285,13 @@ SparseMatrix<number>::end (const unsigned int r)
 {
   Assert (r<m(), ExcIndexRange(r,0,m()));
 
-  // place the iterator on the first entry
-  // past this line, or at the end of the
-  // matrix
+  // place the iterator on the first entry past this line, or at the end of
+  // the matrix
   for (unsigned int i=r+1; i<m(); ++i)
     if (cols->row_length(i) > 0)
       return iterator(this, i, 0);
 
-  // if there is no such line, then take the
-  // end iterator of the matrix
+  // if there is no such line, then take the end iterator of the matrix
   return end();
 }
 
index 60f3753857fe3fac0a31277a3a4e06638495ebc9..f032403de4da6c8164f6304af3c1db0038f13f2d 100644 (file)
@@ -374,20 +374,18 @@ SparseMatrix<number>::add (const number factor,
 }
 
 
+
 namespace internal
 {
   namespace SparseMatrix
   {
     /**
-     * Perform a vmult using the SparseMatrix
-     * data structures, but only using a
-     * subinterval for the row indices.
+     * Perform a vmult using the SparseMatrix data structures, but only using
+     * a subinterval for the row indices.
      *
-     * In the sequential case, this function
-     * is called on all rows, in the parallel
-     * case it may be called on a subrange,
-     * at the discretion of the task
-     * scheduler.
+     * In the sequential case, this function is called on all rows, in the
+     * parallel case it may be called on a subrange, at the discretion of the
+     * task scheduler.
      */
     template <typename number,
              typename InVector,
index e0f102402a019308b33f998c4909a9c6d01dacb0..fe87da3f19aa9e2ca5ab68655ccd57e9bb229187 100644 (file)
@@ -45,35 +45,26 @@ namespace internals
   namespace SparsityPatternTools
   {
     /**
-     * Helper function to get the
-     * column index from a
-     * dereferenced iterator in the
-     * copy_from() function, if
-     * the inner iterator type points
-     * to plain unsigned integers.
+     * Helper function to get the column index from a dereferenced iterator in
+     * the copy_from() function, if the inner iterator type points to plain
+     * unsigned integers.
      */
     unsigned int
     get_column_index_from_iterator (const unsigned int i);
 
     /**
-     * Helper function to get the
-     * column index from a
-     * dereferenced iterator in the
-     * copy_from() function, if
-     * the inner iterator type points
-     * to pairs of unsigned integers
-     * and some other value.
+     * Helper function to get the column index from a dereferenced iterator in
+     * the copy_from() function, if the inner iterator type points to pairs of
+     * unsigned integers and some other value.
      */
     template <typename value>
     unsigned int
     get_column_index_from_iterator (const std::pair<unsigned int, value> &i);
 
     /**
-     * Likewise, but sometimes needed
-     * for certain types of
-     * containers that make the first
-     * element of the pair constant
-     * (such as <tt>std::map</tt>).
+     * Likewise, but sometimes needed for certain types of containers that
+     * make the first element of the pair constant (such as
+     * <tt>std::map</tt>).
      */
     template <typename value>
     unsigned int
@@ -114,86 +105,57 @@ namespace SparsityPatternIterators
               const unsigned int     index);
 
     /**
-     * Constructor. Construct the end
-     * accessor for the given sparsity
-     * pattern.
+     * Constructor. Construct the end accessor for the given sparsity pattern.
      */
     Accessor (const SparsityPattern *matrix);
 
     /**
-     * Row number of the element
-     * represented by this object. This
-     * function can only be called for
-     * entries for which is_valid_entry()
-     * is true.
+     * Row number of the element represented by this object. This function can
+     * only be called for entries for which is_valid_entry() is true.
      */
     unsigned int row () const;
 
     /**
-     * Index in row of the element
-     * represented by this object. This
-     * function can only be called for
-     * entries for which is_valid_entry()
-     * is true.
+     * Index in row of the element represented by this object. This function
+     * can only be called for entries for which is_valid_entry() is true.
      */
     unsigned int index () const;
 
     /**
-     * Column number of the element
-     * represented by this object. This
-     * function can only be called for
-     * entries for which is_valid_entry() is
-     * true.
+     * Column number of the element represented by this object. This function
+     * can only be called for entries for which is_valid_entry() is true.
      */
     unsigned int column () const;
 
     /**
-     * Return whether the sparsity
-     * pattern entry pointed to by this
-     * iterator is valid or not. Note
-     * that after compressing the
-     * sparsity pattern, all entries are
-     * valid. However, before
-     * compression, the sparsity pattern
-     * allocated some memory to be used
-     * while still adding new nonzero
-     * entries; if you create iterators
-     * in this phase of the sparsity
-     * pattern's lifetime, you will
-     * iterate over elements that are not
-     * valid. If this is so, then this
-     * function will return false.
+     * Return whether the sparsity pattern entry pointed to by this iterator
+     * is valid or not. Note that after compressing the sparsity pattern, all
+     * entries are valid. However, before compression, the sparsity pattern
+     * allocated some memory to be used while still adding new nonzero
+     * entries; if you create iterators in this phase of the sparsity
+     * pattern's lifetime, you will iterate over elements that are not
+     * valid. If this is so, then this function will return false.
      */
     inline bool is_valid_entry () const;
 
 
     /**
-     * Comparison. True, if
-     * both iterators point to
-     * the same matrix
-     * position.
+     * Comparison. True, if both iterators point to the same matrix position.
      */
     bool operator == (const Accessor &) const;
 
 
     /**
-     * Comparison
-     * operator. Result is true
-     * if either the first row
-     * number is smaller or if
-     * the row numbers are
-     * equal and the first
-     * index is smaller.
+     * Comparison operator. Result is true if either the first row number is
+     * smaller or if the row numbers are equal and the first index is smaller.
      *
-     * This function is only valid if
-     * both iterators point into the same
+     * This function is only valid if both iterators point into the same
      * sparsity pattern.
      */
     bool operator < (const Accessor &) const;
   protected:
     /**
-     * The sparsity pattern we operate on
-     * accessed.
+     * The sparsity pattern we operate on accessed.
      */
     const SparsityPattern *sparsity_pattern;
 
@@ -208,8 +170,7 @@ namespace SparsityPatternIterators
     unsigned int a_index;
 
     /**
-     * Move the accessor to the next
-     * nonzero entry in the matrix.
+     * Move the accessor to the next nonzero entry in the matrix.
      */
     void advance ();
 
@@ -222,15 +183,13 @@ namespace SparsityPatternIterators
 
 
   /**
-   * STL conforming iterator walking over
-   * the elements of a sparsity pattern.
+   * STL conforming iterator walking over the elements of a sparsity pattern.
    */
   class Iterator
   {
   public:
     /**
-     * Constructor. Create an iterator
-     * into the sparsity pattern @p sp for the
+     * Constructor. Create an iterator into the sparsity pattern @p sp for the
      * given row and the index within it.
      */
     Iterator (const SparsityPattern *sp,
@@ -258,10 +217,7 @@ namespace SparsityPatternIterators
     const Accessor *operator-> () const;
 
     /**
-     * Comparison. True, if
-     * both iterators point to
-     * the same matrix
-     * position.
+     * Comparison. True, if both iterators point to the same matrix position.
      */
     bool operator == (const Iterator &) const;
 
@@ -271,24 +227,17 @@ namespace SparsityPatternIterators
     bool operator != (const Iterator &) const;
 
     /**
-     * Comparison
-     * operator. Result is true
-     * if either the first row
-     * number is smaller or if
-     * the row numbers are
-     * equal and the first
-     * index is smaller.
+     * Comparison operator. Result is true if either the first row number is
+     * smaller or if the row numbers are equal and the first index is smaller.
      *
-     * This function is only valid if
-     * both iterators point into the same
+     * This function is only valid if both iterators point into the same
      * matrix.
      */
     bool operator < (const Iterator &) const;
 
   private:
     /**
-     * Store an object of the
-     * accessor class.
+     * Store an object of the accessor class.
      */
     Accessor accessor;
   };
@@ -309,31 +258,26 @@ class SparsityPattern : public Subscriptor
 {
 public:
   /**
-   * Typedef an iterator class that allows
-   * to walk over all nonzero elements of a
-   * sparsity pattern.
+   * Typedef an iterator class that allows to walk over all nonzero elements
+   * of a sparsity pattern.
    */
   typedef
   SparsityPatternIterators::Iterator
   const_iterator;
 
   /**
-   * Typedef an iterator class that allows
-   * to walk over the nonzero elements of a
-   * row of a sparsity pattern.
+   * Typedef an iterator class that allows to walk over the nonzero elements
+   * of a row of a sparsity pattern.
    */
   typedef
   const unsigned int *row_iterator;
 
   /**
-   * Typedef an iterator class that allows
-   * to walk over all nonzero elements of a
-   * sparsity pattern.
+   * Typedef an iterator class that allows to walk over all nonzero elements
+   * of a sparsity pattern.
    *
-   * Since the iterator does not allow to
-   * modify the sparsity pattern, this type
-   * is the same as that for @p
-   * const_iterator.
+   * Since the iterator does not allow to modify the sparsity pattern, this
+   * type is the same as that for @p const_iterator.
    */
   typedef
   SparsityPatternIterators::Iterator
@@ -341,28 +285,18 @@ public:
 
 
   /**
-   * Define a value which is used
-   * to indicate that a certain
-   * value in the #colnums array
-   * is unused, i.e. does not
-   * represent a certain column
-   * number index.
+   * Define a value which is used to indicate that a certain value in the
+   * #colnums array is unused, i.e. does not represent a certain column number
+   * index.
    *
-   * Indices with this invalid
-   * value are used to insert new
-   * entries to the sparsity
-   * pattern using the add() member
-   * function, and are removed when
+   * Indices with this invalid value are used to insert new entries to the
+   * sparsity pattern using the add() member function, and are removed when
    * calling compress().
    *
-   * You should not assume that the
-   * variable declared here has a
-   * certain value. The
-   * initialization is given here
-   * only to enable the compiler to
-   * perform some optimizations,
-   * but the actual value of the
-   * variable may change over time.
+   * You should not assume that the variable declared here has a certain
+   * value. The initialization is given here only to enable the compiler to
+   * perform some optimizations, but the actual value of the variable may
+   * change over time.
    */
   static const unsigned int invalid_entry = numbers::invalid_unsigned_int;
 
@@ -372,64 +306,37 @@ public:
    */
 // @{
   /**
-   * Initialize the matrix empty,
-   * that is with no memory
-   * allocated. This is useful if
-   * you want such objects as
-   * member variables in other
-   * classes. You can make the
-   * structure usable by calling
-   * the reinit() function.
+   * Initialize the matrix empty, that is with no memory allocated. This is
+   * useful if you want such objects as member variables in other classes. You
+   * can make the structure usable by calling the reinit() function.
    */
   SparsityPattern ();
 
   /**
-   * Copy constructor. This
-   * constructor is only allowed to
-   * be called if the matrix
-   * structure to be copied is
-   * empty. This is so in order to
-   * prevent involuntary copies of
-   * objects for temporaries, which
-   * can use large amounts of
-   * computing time.  However, copy
-   * constructors are needed if yo
-   * want to use the STL data types
-   * on classes like this, e.g. to
-   * write such statements like
-   * <tt>v.push_back
-   * (SparsityPattern());</tt>,
-   * with <tt>v</tt> a vector of
-   * SparsityPattern objects.
+   * Copy constructor. This constructor is only allowed to be called if the
+   * matrix structure to be copied is empty. This is so in order to prevent
+   * involuntary copies of objects for temporaries, which can use large
+   * amounts of computing time.  However, copy constructors are needed if yo
+   * want to use the STL data types on classes like this, e.g. to write such
+   * statements like <tt>v.push_back (SparsityPattern());</tt>, with
+   * <tt>v</tt> a vector of SparsityPattern objects.
    *
-   * Usually, it is sufficient to
-   * use the explicit keyword to
-   * disallow unwanted temporaries,
-   * but for the STL vectors, this
-   * does not work. Since copying a
-   * structure like this is not
-   * useful anyway because multiple
-   * matrices can use the same
-   * sparsity structure, copies are
-   * only allowed for empty
-   * objects, as described above.
+   * Usually, it is sufficient to use the explicit keyword to disallow
+   * unwanted temporaries, but for the STL vectors, this does not work. Since
+   * copying a structure like this is not useful anyway because multiple
+   * matrices can use the same sparsity structure, copies are only allowed for
+   * empty objects, as described above.
    */
   SparsityPattern (const SparsityPattern &);
 
   /**
-   * Initialize a rectangular
-   * matrix.
+   * Initialize a rectangular matrix.
    *
    * @arg m number of rows
    * @arg n number of columns
-   * @arg max_per_row maximum
-   * number of nonzero entries per row
-   *
-   * @arg optimize_diagonal store
-   * diagonal entries first in row;
-   * see optimize_diagonal(). This
-   * takes effect for quadratic
-   * matrices only.
+   * @arg max_per_row maximum number of nonzero entries per row
+   * @arg optimize_diagonal store diagonal entries first in row; see
+   * optimize_diagonal(). This takes effect for quadratic matrices only.
    */
   SparsityPattern (const unsigned int m,
                    const unsigned int n,
@@ -437,22 +344,14 @@ public:
                    const bool optimize_diagonal = true);
 
   /**
-   * Initialize a rectangular
-   * matrix.
+   * Initialize a rectangular matrix.
    *
    * @arg m number of rows
    * @arg n number of columns
-   *
-   * @arg row_lengths possible
-   * number of nonzero entries for
-   * each row.  This vector must
-   * have one entry for each row.
-   *
-   * @arg optimize_diagonal store
-   * diagonal entries first in row;
-   * see optimize_diagonal(). This
-   * takes effect for quadratic
-   * matrices only.
+   * @arg row_lengths possible number of nonzero entries for each row.  This
+   * vector must have one entry for each row.
+   * @arg optimize_diagonal store diagonal entries first in row; see
+   * optimize_diagonal(). This takes effect for quadratic matrices only.
    */
   SparsityPattern (const unsigned int               m,
                    const unsigned int               n,
@@ -460,17 +359,12 @@ public:
                    const bool optimize_diagonal = true);
 
   /**
-   * Initialize a quadratic matrix
-   * of dimension <tt>n</tt> with
-   * at most <tt>max_per_row</tt>
-   * nonzero entries per row.
+   * Initialize a quadratic matrix of dimension <tt>n</tt> with at most
+   * <tt>max_per_row</tt> nonzero entries per row.
    *
-   * This constructor automatically
-   * enables optimized storage of
-   * diagonal elements. To avoid
-   * this, use the constructor
-   * taking row and column numbers
-   * separately.
+   * This constructor automatically enables optimized storage of diagonal
+   * elements. To avoid this, use the constructor taking row and column
+   * numbers separately.
    */
   SparsityPattern (const unsigned int n,
                    const unsigned int max_per_row);
@@ -479,15 +373,10 @@ public:
    * Initialize a quadratic matrix.
    *
    * @arg m number of rows and columns
-   *
-   * @arg row_lengths possible
-   * number of nonzero entries for
-   * each row.  This vector must
-   * have one entry for each row.
-   *
-   * @arg optimize_diagonal store
-   * diagonal entries first in row;
-   * see optimize_diagonal().
+   * @arg row_lengths possible number of nonzero entries for each row.  This
+   * vector must have one entry for each row.
+   * @arg optimize_diagonal store diagonal entries first in row; see
+   * optimize_diagonal().
    */
   SparsityPattern (const unsigned int               m,
                    const std::vector<unsigned int> &row_lengths,
@@ -496,44 +385,24 @@ public:
   /**
    * Make a copy with extra off-diagonals.
    *
-   * This constructs objects intended for
-   * the application of the ILU(n)-method
-   * or other incomplete decompositions.
-   * Therefore, additional to the original
-   * entry structure, space for
-   * <tt>extra_off_diagonals</tt>
-   * side-diagonals is provided on both
-   * sides of the main diagonal.
-   *
-   * <tt>max_per_row</tt> is the
-   * maximum number of nonzero
-   * elements per row which this
-   * structure is to hold. It is
-   * assumed that this number is
-   * sufficiently large to
-   * accommodate both the elements
-   * in <tt>original</tt> as well
-   * as the new off-diagonal
-   * elements created by this
-   * constructor. You will usually
-   * want to give the same number
-   * as you gave for
-   * <tt>original</tt> plus the
-   * number of side diagonals times
-   * two. You may however give a
-   * larger value if you wish to
-   * add further nonzero entries
-   * for the decomposition based on
-   * other criteria than their
-   * being on side-diagonals.
-   *
-   * This function requires that
-   * <tt>original</tt> refers to a
-   * quadratic matrix structure.
-   * It must be compressed. The
-   * matrix structure is not
-   * compressed after this function
-   * finishes.
+   * This constructs objects intended for the application of the ILU(n)-method
+   * or other incomplete decompositions.  Therefore, additional to the
+   * original entry structure, space for <tt>extra_off_diagonals</tt>
+   * side-diagonals is provided on both sides of the main diagonal.
+   *
+   * <tt>max_per_row</tt> is the maximum number of nonzero elements per row
+   * which this structure is to hold. It is assumed that this number is
+   * sufficiently large to accommodate both the elements in <tt>original</tt>
+   * as well as the new off-diagonal elements created by this constructor. You
+   * will usually want to give the same number as you gave for
+   * <tt>original</tt> plus the number of side diagonals times two. You may
+   * however give a larger value if you wish to add further nonzero entries
+   * for the decomposition based on other criteria than their being on
+   * side-diagonals.
+   *
+   * This function requires that <tt>original</tt> refers to a quadratic
+   * matrix structure.  It must be compressed. The matrix structure is not
+   * compressed after this function finishes.
    */
   SparsityPattern (const SparsityPattern &original,
                    const unsigned int      max_per_row,
@@ -545,25 +414,19 @@ public:
   ~SparsityPattern ();
 
   /**
-   * Copy operator. For this the
-   * same holds as for the copy
-   * constructor: it is declared,
-   * defined and fine to be called,
-   * but the latter only for empty
+   * Copy operator. For this the same holds as for the copy constructor: it is
+   * declared, defined and fine to be called, but the latter only for empty
    * objects.
    */
   SparsityPattern &operator = (const SparsityPattern &);
 
   /**
-   * Reallocate memory and set up data
-   * structures for a new matrix with
-   * <tt>m </tt>rows and <tt>n</tt> columns,
-   * with at most <tt>max_per_row</tt>
+   * Reallocate memory and set up data structures for a new matrix with <tt>m
+   * </tt>rows and <tt>n</tt> columns, with at most <tt>max_per_row</tt>
    * nonzero entries per row.
    *
-   * This function simply maps its
-   * operations to the other
-   * <tt>reinit</tt> function.
+   * This function simply maps its operations to the other <tt>reinit</tt>
+   * function.
    */
   void reinit (const unsigned int m,
                const unsigned int n,
@@ -571,29 +434,18 @@ public:
                const bool optimize_diagonal = true);
 
   /**
-   * Reallocate memory for a matrix
-   * of size <tt>m x n</tt>. The
-   * number of entries for each row
-   * is taken from the array
-   * <tt>row_lengths</tt> which has to
-   * give this number of each row
-   * <tt>i=1...m</tt>.
+   * Reallocate memory for a matrix of size <tt>m x n</tt>. The number of
+   * entries for each row is taken from the array <tt>row_lengths</tt> which
+   * has to give this number of each row <tt>i=1...m</tt>.
    *
-   * If <tt>m*n==0</tt> all memory is freed,
-   * resulting in a total reinitialization
-   * of the object. If it is nonzero, new
-   * memory is only allocated if the new
-   * size extends the old one. This is done
-   * to save time and to avoid fragmentation
-   * of the heap.
+   * If <tt>m*n==0</tt> all memory is freed, resulting in a total
+   * reinitialization of the object. If it is nonzero, new memory is only
+   * allocated if the new size extends the old one. This is done to save time
+   * and to avoid fragmentation of the heap.
    *
-   * If the number of rows equals
-   * the number of columns and the
-   * last parameter is true,
-   * diagonal elements are stored
-   * first in each row to allow
-   * optimized access in relaxation
-   * methods of SparseMatrix.
+   * If the number of rows equals the number of columns and the last parameter
+   * is true, diagonal elements are stored first in each row to allow
+   * optimized access in relaxation methods of SparseMatrix.
    */
   void reinit (const unsigned int               m,
                const unsigned int               n,
@@ -601,8 +453,7 @@ public:
                const bool optimize_diagonal = true);
 
   /**
-   * Same as above, but with a
-   * VectorSlice argument instead.
+   * Same as above, but with a VectorSlice argument instead.
    */
   void reinit (const unsigned int               m,
                const unsigned int               n,
@@ -610,103 +461,52 @@ public:
                const bool optimize_diagonal = true);
 
   /**
-   * This function compresses the sparsity
-   * structure that this object represents.
-   * It does so by eliminating unused
-   * entries and sorting the remaining ones
-   * to allow faster access by usage of
-   * binary search algorithms. A special
-   * sorting scheme is used for the
-   * diagonal entry of quadratic matrices,
-   * which is always the first entry of
-   * each row.
+   * This function compresses the sparsity structure that this object
+   * represents.  It does so by eliminating unused entries and sorting the
+   * remaining ones to allow faster access by usage of binary search
+   * algorithms. A special sorting scheme is used for the diagonal entry of
+   * quadratic matrices, which is always the first entry of each row.
    *
-   * The memory which is no more
-   * needed is released.
+   * The memory which is no more needed is released.
    *
-   * SparseMatrix objects require the
-   * SparsityPattern objects they are
-   * initialized with to be compressed, to
-   * reduce memory requirements.
+   * SparseMatrix objects require the SparsityPattern objects they are
+   * initialized with to be compressed, to reduce memory requirements.
    */
   void compress ();
 
   /**
-   * This function can be used as a
-   * replacement for reinit(),
-   * subsequent calls to add() and
-   * a final call to close() if you
-   * know exactly in advance the
-   * entries that will form the
-   * matrix sparsity pattern.
-   *
-   * The first two parameters
-   * determine the size of the
-   * matrix. For the two last ones,
-   * note that a sparse matrix can
-   * be described by a sequence of
-   * rows, each of which is
-   * represented by a sequence of
-   * pairs of column indices and
-   * values. In the present
-   * context, the begin() and
-   * end() parameters designate
-   * iterators (of forward iterator
-   * type) into a container, one
-   * representing one row. The
-   * distance between begin()
-   * and end() should therefore
-   * be equal to
-   * n_rows(). These iterators
-   * may be iterators of
-   * <tt>std::vector</tt>,
-   * <tt>std::list</tt>, pointers into a
-   * C-style array, or any other
-   * iterator satisfying the
-   * requirements of a forward
-   * iterator. The objects pointed
-   * to by these iterators
-   * (i.e. what we get after
-   * applying <tt>operator*</tt> or
-   * <tt>operator-></tt> to one of these
-   * iterators) must be a container
-   * itself that provides functions
-   * <tt>begin</tt> and <tt>end</tt>
-   * designating a range of
-   * iterators that describe the
-   * contents of one
-   * line. Dereferencing these
-   * inner iterators must either
-   * yield a pair of an unsigned
-   * integer as column index and a
-   * value of arbitrary type (such
-   * a type would be used if we
-   * wanted to describe a sparse
-   * matrix with one such object),
-   * or simply an unsigned integer
-   * (of we only wanted to describe
-   * a sparsity pattern). The
-   * function is able to determine
-   * itself whether an unsigned
-   * integer or a pair is what we
-   * get after dereferencing the
-   * inner iterators, through some
-   * template magic.
-   *
-   * While the order of the outer
-   * iterators denotes the
-   * different rows of the matrix,
-   * the order of the inner
-   * iterator denoting the columns
-   * does not matter, as they are
-   * sorted internal to this
-   * function anyway.
-   *
-   * Since that all sounds very
-   * complicated, consider the
-   * following example code, which
-   * may be used to fill a sparsity
-   * pattern:
+   * This function can be used as a replacement for reinit(), subsequent calls
+   * to add() and a final call to close() if you know exactly in advance the
+   * entries that will form the matrix sparsity pattern.
+   *
+   * The first two parameters determine the size of the matrix. For the two
+   * last ones, note that a sparse matrix can be described by a sequence of
+   * rows, each of which is represented by a sequence of pairs of column
+   * indices and values. In the present context, the begin() and end()
+   * parameters designate iterators (of forward iterator type) into a
+   * container, one representing one row. The distance between begin() and
+   * end() should therefore be equal to n_rows(). These iterators may be
+   * iterators of <tt>std::vector</tt>, <tt>std::list</tt>, pointers into a
+   * C-style array, or any other iterator satisfying the requirements of a
+   * forward iterator. The objects pointed to by these iterators (i.e. what we
+   * get after applying <tt>operator*</tt> or <tt>operator-></tt> to one of
+   * these iterators) must be a container itself that provides functions
+   * <tt>begin</tt> and <tt>end</tt> designating a range of iterators that
+   * describe the contents of one line. Dereferencing these inner iterators
+   * must either yield a pair of an unsigned integer as column index and a
+   * value of arbitrary type (such a type would be used if we wanted to
+   * describe a sparse matrix with one such object), or simply an unsigned
+   * integer (of we only wanted to describe a sparsity pattern). The function
+   * is able to determine itself whether an unsigned integer or a pair is what
+   * we get after dereferencing the inner iterators, through some template
+   * magic.
+   *
+   * While the order of the outer iterators denotes the different rows of the
+   * matrix, the order of the inner iterator denoting the columns does not
+   * matter, as they are sorted internal to this function anyway.
+   *
+   * Since that all sounds very complicated, consider the following example
+   * code, which may be used to fill a sparsity pattern:
    * @code
    * std::vector<std::vector<unsigned int> > column_indices (n_rows);
    * for (unsigned int row=0; row<n_rows; ++row)
@@ -718,25 +518,15 @@ public:
    *                     column_indices.end());
    * @endcode
    *
-   * Note that this example works
-   * since the iterators
-   * dereferenced yield containers
-   * with functions <tt>begin</tt> and
-   * <tt>end</tt> (namely
-   * <tt>std::vector</tt>s), and the
-   * inner iterators dereferenced
-   * yield unsigned integers as
-   * column indices. Note that we
-   * could have replaced each of
-   * the two <tt>std::vector</tt>
-   * occurrences by <tt>std::list</tt>,
-   * and the inner one by
-   * <tt>std::set</tt> as well.
+   * Note that this example works since the iterators dereferenced yield
+   * containers with functions <tt>begin</tt> and <tt>end</tt> (namely
+   * <tt>std::vector</tt>s), and the inner iterators dereferenced yield
+   * unsigned integers as column indices. Note that we could have replaced
+   * each of the two <tt>std::vector</tt> occurrences by <tt>std::list</tt>,
+   * and the inner one by <tt>std::set</tt> as well.
    *
-   * Another example would be as
-   * follows, where we initialize a
-   * whole matrix, not only a
-   * sparsity pattern:
+   * Another example would be as follows, where we initialize a whole matrix,
+   * not only a sparsity pattern:
    * @code
    * std::vector<std::map<unsigned int,double> > entries (n_rows);
    * for (unsigned int row=0; row<n_rows; ++row)
@@ -752,22 +542,13 @@ public:
    *                   column_indices.end());
    * @endcode
    *
-   * This example works because
-   * dereferencing iterators of the
-   * inner type yields a pair of
-   * unsigned integers and a value,
-   * the first of which we take as
-   * column index. As previously,
-   * the outer <tt>std::vector</tt>
-   * could be replaced by
-   * <tt>std::list</tt>, and the inner
-   * <tt>std::map<unsigned int,double></tt>
-   * could be replaced by
-   * <tt>std::vector<std::pair<unsigned int,double> ></tt>,
-   * or a list or set of such
-   * pairs, as they all return
-   * iterators that point to such
-   * pairs.
+   * This example works because dereferencing iterators of the inner type
+   * yields a pair of unsigned integers and a value, the first of which we
+   * take as column index. As previously, the outer <tt>std::vector</tt> could
+   * be replaced by <tt>std::list</tt>, and the inner <tt>std::map<unsigned
+   * int,double></tt> could be replaced by <tt>std::vector<std::pair<unsigned
+   * int,double> ></tt>, or a list or set of such pairs, as they all return
+   * iterators that point to such pairs.
    */
   template <typename ForwardIterator>
   void copy_from (const unsigned int    n_rows,
@@ -777,12 +558,9 @@ public:
                   const bool optimize_diagonal = true);
 
   /**
-   * Copy data from an object of type
-   * CompressedSparsityPattern,
-   * CompressedSetSparsityPattern or
-   * CompressedSimpleSparsityPattern.
-   * Previous content of this object is
-   * lost, and the sparsity pattern is in
+   * Copy data from an object of type CompressedSparsityPattern,
+   * CompressedSetSparsityPattern or CompressedSimpleSparsityPattern.
+   * Previous content of this object is lost, and the sparsity pattern is in
    * compressed mode afterwards.
    */
   template <typename CompressedSparsityType>
@@ -790,14 +568,10 @@ public:
                   const bool optimize_diagonal = true);
 
   /**
-   * Take a full matrix and use its
-   * nonzero entries to generate a
-   * sparse matrix entry pattern
-   * for this object.
+   * Take a full matrix and use its nonzero entries to generate a sparse
+   * matrix entry pattern for this object.
    *
-   * Previous content of this
-   * object is lost, and the
-   * sparsity pattern is in
+   * Previous content of this object is lost, and the sparsity pattern is in
    * compressed mode afterwards.
    */
   template <typename number>
@@ -805,37 +579,28 @@ public:
                   const bool optimize_diagonal = true);
 
   /**
-   * Make the sparsity pattern
-   * symmetric by adding the
-   * sparsity pattern of the
+   * Make the sparsity pattern symmetric by adding the sparsity pattern of the
    * transpose object.
    *
-   * This function throws an
-   * exception if the sparsity
-   * pattern does not represent a
-   * quadratic matrix.
+   * This function throws an exception if the sparsity pattern does not
+   * represent a quadratic matrix.
    */
   void symmetrize ();
 
   /**
-                                        * Add a nonzero entry to the matrix.
-                                        * This function may only be called
-                                        * for non-compressed sparsity patterns.
-                                        *
-                                        * If the entry already exists, nothing
-                                        * bad happens.
-                                        */
+   * Add a nonzero entry to the matrix.  This function may only be called for
+   * non-compressed sparsity patterns.
+   *
+   * If the entry already exists, nothing bad happens.
+   */
   void add (const unsigned int i,
             const unsigned int j);
 
   /**
-   * Add several nonzero entries to the
-   * specified matrix row.  This function
-   * may only be called for
-   * non-compressed sparsity patterns.
+   * Add several nonzero entries to the specified matrix row.  This function
+   * may only be called for non-compressed sparsity patterns.
    *
-   * If some of the entries already
-   * exist, nothing bad happens.
+   * If some of the entries already exist, nothing bad happens.
    */
   template <typename ForwardIterator>
   void add_entries (const unsigned int row,
@@ -850,10 +615,9 @@ public:
 // @{
 
   /**
-   * STL-like iterator with the first entry
-   * of the matrix. The resulting iterator
-   * can be used to walk over all nonzero
-   * entries of the sparsity pattern.
+   * STL-like iterator with the first entry of the matrix. The resulting
+   * iterator can be used to walk over all nonzero entries of the sparsity
+   * pattern.
    */
   inline iterator begin () const;
 
@@ -863,56 +627,42 @@ public:
   inline iterator end () const;
 
   /**
-   * STL-like iterator with the first entry
-   * of row <tt>r</tt>.
+   * STL-like iterator with the first entry of row <tt>r</tt>.
    *
-   * Note that if the given row is empty,
-   * i.e. does not contain any nonzero
-   * entries, then the iterator returned by
-   * this function equals
-   * <tt>end(r)</tt>. Note also that the
-   * iterator may not be dereferencable in
+   * Note that if the given row is empty, i.e. does not contain any nonzero
+   * entries, then the iterator returned by this function equals
+   * <tt>end(r)</tt>. Note also that the iterator may not be dereferencable in
    * that case.
    */
   inline iterator begin (const unsigned int r) const;
 
   /**
-   * Final iterator of row <tt>r</tt>. It
-   * points to the first element past the
-   * end of line @p r, or past the end of
-   * the entire sparsity pattern.
+   * Final iterator of row <tt>r</tt>. It points to the first element past the
+   * end of line @p r, or past the end of the entire sparsity pattern.
    *
-   * Note that the end iterator is not
-   * necessarily dereferencable. This is in
-   * particular the case if it is the end
-   * iterator for the last row of a matrix.
+   * Note that the end iterator is not necessarily dereferencable. This is in
+   * particular the case if it is the end iterator for the last row of a
+   * matrix.
    */
   inline iterator end (const unsigned int r) const;
 
   /**
-   * STL-like iterator with the first entry
-   * of row <tt>r</tt>.
+   * STL-like iterator with the first entry of row <tt>r</tt>.
    *
-   * Note that if the given row is empty,
-   * i.e. does not contain any nonzero
-   * entries, then the iterator returned by
-   * this function equals
-   * <tt>end(r)</tt>. Note also that the
-   * iterator may not be dereferencable in
+   * Note that if the given row is empty, i.e. does not contain any nonzero
+   * entries, then the iterator returned by this function equals
+   * <tt>end(r)</tt>. Note also that the iterator may not be dereferencable in
    * that case.
    */
   inline row_iterator row_begin (const unsigned int r) const;
 
   /**
-   * Final iterator of row <tt>r</tt>. It
-   * points to the first element past the
-   * end of line @p r, or past the end of
-   * the entire sparsity pattern.
+   * Final iterator of row <tt>r</tt>. It points to the first element past the
+   * end of line @p r, or past the end of the entire sparsity pattern.
    *
-   * Note that the end iterator is not
-   * necessarily dereferencable. This is in
-   * particular the case if it is the end
-   * iterator for the last row of a matrix.
+   * Note that the end iterator is not necessarily dereferencable. This is in
+   * particular the case if it is the end iterator for the last row of a
+   * matrix.
    */
   inline row_iterator row_end (const unsigned int r) const;
 
@@ -927,66 +677,50 @@ public:
   bool operator == (const SparsityPattern &)  const;
 
   /**
-   * Return whether the object is empty. It
-   * is empty if no memory is allocated,
-   * which is the same as that both
-   * dimensions are zero.
+   * Return whether the object is empty. It is empty if no memory is
+   * allocated, which is the same as that both dimensions are zero.
    */
   bool empty () const;
 
   /**
-   * Return the maximum number of entries per
-   * row. Before compression, this equals the
-   * number given to the constructor, while
-   * after compression, it equals the maximum
-   * number of entries actually allocated by
-   * the user.
+   * Return the maximum number of entries per row. Before compression, this
+   * equals the number given to the constructor, while after compression, it
+   * equals the maximum number of entries actually allocated by the user.
    */
   unsigned int max_entries_per_row () const;
 
   /**
-   * Compute the bandwidth of the matrix
-   * represented by this structure. The
-   * bandwidth is the maximum of $|i-j|$
-   * for which the index pair $(i,j)$
-   * represents a nonzero entry of the
-   * matrix. Consequently, the maximum
-   * bandwidth a $n\times m$ matrix can
-   * have is $\max\{n-1,m-1\}$.
+   * Compute the bandwidth of the matrix represented by this structure. The
+   * bandwidth is the maximum of $|i-j|$ for which the index pair $(i,j)$
+   * represents a nonzero entry of the matrix. Consequently, the maximum
+   * bandwidth a $n\times m$ matrix can have is $\max\{n-1,m-1\}$.
    */
   unsigned int bandwidth () const;
 
   /**
-   * Return the number of nonzero elements of
-   * this matrix. Actually, it returns the
-   * number of entries in the sparsity
-   * pattern; if any of the entries should
-   * happen to be zero, it is counted
-   * anyway.
+   * Return the number of nonzero elements of this matrix. Actually, it
+   * returns the number of entries in the sparsity pattern; if any of the
+   * entries should happen to be zero, it is counted anyway.
    *
-   * This function may only be called if the
-   * matrix struct is compressed. It does not
-   * make too much sense otherwise anyway.
+   * This function may only be called if the matrix struct is compressed. It
+   * does not make too much sense otherwise anyway.
    */
   std::size_t n_nonzero_elements () const;
 
   /**
-   * Return whether the structure is
-   * compressed or not.
+   * Return whether the structure is compressed or not.
    */
   bool is_compressed () const;
 
   /**
-   * Return number of rows of this
-   * matrix, which equals the dimension
-   * of the image space.
+   * Return number of rows of this matrix, which equals the dimension of the
+   * image space.
    */
   inline unsigned int n_rows () const;
 
   /**
-   * Return number of columns of this
-   * matrix, which equals the dimension
-   * of the range space.
+   * Return number of columns of this matrix, which equals the dimension of
+   * the range space.
    */
   inline unsigned int n_cols () const;
 
@@ -996,66 +730,44 @@ public:
   unsigned int row_length (const unsigned int row) const;
 
   /**
-   * Determine whether the matrix
-   * uses special convention for
-   * quadratic matrices.
+   * Determine whether the matrix uses special convention for quadratic
+   * matrices.
    *
-   * A return value <tt>true</tt> means
-   * that diagonal elements are stored
-   * first in each row. A number of
-   * functions in this class and the
-   * library in general, for example
-   * relaxation methods like Jacobi() and
-   * SOR(), require this to make their
-   * operations more efficient, since they
-   * need to quickly access the diagonal
-   * elements and do not have to search for
-   * them if they are the first element of
-   * each row. A side effect of this scheme
-   * is that each row contains at least one
-   * element, even if the row is empty
-   * (i.e. the diagonal element exists, but
-   * has value zero).
+   * A return value <tt>true</tt> means that diagonal elements are stored
+   * first in each row. A number of functions in this class and the library in
+   * general, for example relaxation methods like Jacobi() and SOR(), require
+   * this to make their operations more efficient, since they need to quickly
+   * access the diagonal elements and do not have to search for them if they
+   * are the first element of each row. A side effect of this scheme is that
+   * each row contains at least one element, even if the row is empty
+   * (i.e. the diagonal element exists, but has value zero).
    *
-   * A return value <tt>false</tt> means
-   * that diagonal elements are stored
-   * anywhere in the row, or not at all. In
-   * particular, a row or even the whole
-   * matrix may be empty. This can be used
-   * if you have block matrices where the
-   * off-diagonal blocks are quadratic but
-   * are never used for operations like the
-   * ones mentioned above. In this case,
-   * some memory can be saved by not using
-   * the diagonal storage optimization.
+   * A return value <tt>false</tt> means that diagonal elements are stored
+   * anywhere in the row, or not at all. In particular, a row or even the
+   * whole matrix may be empty. This can be used if you have block matrices
+   * where the off-diagonal blocks are quadratic but are never used for
+   * operations like the ones mentioned above. In this case, some memory can
+   * be saved by not using the diagonal storage optimization.
    */
   bool optimize_diagonal () const;
 
   /**
-   * Return whether this object stores only
-   * those entries that have been added
-   * explicitly, or if the sparsity pattern
-   * contains elements that have been added
-   * through other means (implicitly) while
-   * building it. For the current class,
-   * the result is true iff optimize_diag
-   * in the constructor or reinit() calls
-   * has been set to false, or if the
-   * represented matrix is not square.
+   * Return whether this object stores only those entries that have been added
+   * explicitly, or if the sparsity pattern contains elements that have been
+   * added through other means (implicitly) while building it. For the current
+   * class, the result is true iff optimize_diag in the constructor or
+   * reinit() calls has been set to false, or if the represented matrix is not
+   * square.
    *
-   * This function mainly serves the
-   * purpose of describing the current
-   * class in cases where several kinds of
-   * sparsity patterns can be passed as
+   * This function mainly serves the purpose of describing the current class
+   * in cases where several kinds of sparsity patterns can be passed as
    * template arguments.
    */
   bool stores_only_added_elements () const;
 
   /**
-   * Determine an estimate for the
-   * memory consumption (in bytes)
-   * of this object. See
-   * MemoryConsumption.
+   * Determine an estimate for the memory consumption (in bytes) of this
+   * object. See MemoryConsumption.
    */
   std::size_t memory_consumption () const;
 
@@ -1065,97 +777,64 @@ public:
    */
 // @{
   /**
-   * Return the index of the matrix
-   * element with row number <tt>i</tt>
-   * and column number <tt>j</tt>. If
-   * the matrix element is not a
-   * nonzero one, return
-   * SparsityPattern::invalid_entry.
+   * Return the index of the matrix element with row number <tt>i</tt> and
+   * column number <tt>j</tt>. If the matrix element is not a nonzero one,
+   * return SparsityPattern::invalid_entry.
    *
-   * This function is usually
-   * called by the
-   * SparseMatrix::operator()(). It
-   * may only be called for
-   * compressed sparsity patterns,
-   * since in this case searching
-   * whether the entry exists can
-   * be done quite fast with a
-   * binary sort algorithm because
-   * the column numbers are sorted.
+   * This function is usually called by the SparseMatrix::operator()(). It may
+   * only be called for compressed sparsity patterns, since in this case
+   * searching whether the entry exists can be done quite fast with a binary
+   * sort algorithm because the column numbers are sorted.
    *
-   * If <tt>m</tt> is the number of
-   * entries in <tt>row</tt>, then the
-   * complexity of this function is
-   * <i>log(m)</i> if the sparsity
-   * pattern is compressed.
+   * If <tt>m</tt> is the number of entries in <tt>row</tt>, then the
+   * complexity of this function is <i>log(m)</i> if the sparsity pattern is
+   * compressed.
    *
-   * @deprecated Use
-   * SparseMatrix::const_iterator
+   * @deprecated Use SparseMatrix::const_iterator
    */
   unsigned int operator() (const unsigned int i,
                            const unsigned int j) const;
 
   /**
-   * This is the inverse operation
-   * to operator()(): given a
-   * global index, find out row and
-   * column of the matrix entry to
-   * which it belongs. The returned
-   * value is the pair composed of
-   * row and column index.
+   * This is the inverse operation to operator()(): given a global index, find
+   * out row and column of the matrix entry to which it belongs. The returned
+   * value is the pair composed of row and column index.
    *
-   * This function may only be
-   * called if the sparsity pattern
-   * is closed. The global index
-   * must then be between zero and
-   * n_nonzero_elements().
+   * This function may only be called if the sparsity pattern is closed. The
+   * global index must then be between zero and n_nonzero_elements().
    *
-   * If <tt>N</tt> is the number of
-   * rows of this matrix, then the
-   * complexity of this function is
-   * <i>log(N)</i>.
+   * If <tt>N</tt> is the number of rows of this matrix, then the complexity
+   * of this function is <i>log(N)</i>.
    */
   std::pair<unsigned int, unsigned int>
   matrix_position (const unsigned int global_index) const;
 
   /**
-   * Check if a value at a certain
-   * position may be non-zero.
+   * Check if a value at a certain position may be non-zero.
    */
   bool exists (const unsigned int i,
                const unsigned int j) const;
 
   /**
-   * The index of a global matrix
-   * entry in its row.
+   * The index of a global matrix entry in its row.
    *
-   * This function is analogous to
-   * operator(), but it computes
-   * the index not with respect to
-   * the total field, but only with
-   * respect to the row <tt>j</tt>.
+   * This function is analogous to operator(), but it computes the index not
+   * with respect to the total field, but only with respect to the row
+   * <tt>j</tt>.
    */
   unsigned int row_position(const unsigned int i,
                             const unsigned int j) const;
 
   /**
-   * Access to column number field.
-   * Return the column number of
-   * the <tt>index</tt>th entry in
-   * <tt>row</tt>. Note that if
-   * diagonal elements are
-   * optimized, the first element
-   * in each row is the diagonal
-   * element,
+   * Access to column number field.  Return the column number of the
+   * <tt>index</tt>th entry in <tt>row</tt>. Note that if diagonal elements
+   * are optimized, the first element in each row is the diagonal element,
    * i.e. <tt>column_number(row,0)==row</tt>.
    *
-   * If the sparsity pattern is
-   * already compressed, then
-   * (except for the diagonal
-   * element), the entries are
-   * sorted by columns,
-   * i.e. <tt>column_number(row,i)</tt>
-   * <tt><</tt> <tt>column_number(row,i+1)</tt>.
+   * If the sparsity pattern is already compressed, then (except for the
+   * diagonal element), the entries are sorted by columns,
+   * i.e. <tt>column_number(row,i)</tt> <tt><</tt>
+   * <tt>column_number(row,i+1)</tt>.
    */
   unsigned int column_number (const unsigned int row,
                               const unsigned int index) const;
@@ -1167,98 +846,64 @@ public:
    */
 // @{
   /**
-   * Write the data of this object
-   * en bloc to a file. This is
-   * done in a binary mode, so the
-   * output is neither readable by
-   * humans nor (probably) by other
-   * computers using a different
-   * operating system of number
-   * format.
+   * Write the data of this object en bloc to a file. This is done in a binary
+   * mode, so the output is neither readable by humans nor (probably) by other
+   * computers using a different operating system of number format.
    *
-   * The purpose of this function
-   * is that you can swap out
-   * matrices and sparsity pattern
-   * if you are short of memory,
-   * want to communicate between
-   * different programs, or allow
-   * objects to be persistent
-   * across different runs of the
-   * program.
+   * The purpose of this function is that you can swap out matrices and
+   * sparsity pattern if you are short of memory, want to communicate between
+   * different programs, or allow objects to be persistent across different
+   * runs of the program.
    */
   void block_write (std::ostream &out) const;
 
   /**
-   * Read data that has previously
-   * been written by block_write()
-   * from a file. This is done
-   * using the inverse operations
-   * to the above function, so it
-   * is reasonably fast because the
-   * bitstream is not interpreted
-   * except for a few numbers up
-   * front.
+   * Read data that has previously been written by block_write() from a
+   * file. This is done using the inverse operations to the above function, so
+   * it is reasonably fast because the bitstream is not interpreted except for
+   * a few numbers up front.
    *
-   * The object is resized on this
-   * operation, and all previous
-   * contents are lost.
+   * The object is resized on this operation, and all previous contents are
+   * lost.
    *
-   * A primitive form of error
-   * checking is performed which
-   * will recognize the bluntest
-   * attempts to interpret some
-   * data as a vector stored
-   * bitwise to a file, but not
-   * more.
+   * A primitive form of error checking is performed which will recognize the
+   * bluntest attempts to interpret some data as a vector stored bitwise to a
+   * file, but not more.
    */
   void block_read (std::istream &in);
 
   /**
-   * Print the sparsity of the
-   * matrix. The output consists of
-   * one line per row of the format
-   * <tt>[i,j1,j2,j3,...]</tt>. <i>i</i>
-   * is the row number and
-   * <i>jn</i> are the allocated
-   * columns in this row.
+   * Print the sparsity of the matrix. The output consists of one line per row
+   * of the format <tt>[i,j1,j2,j3,...]</tt>. <i>i</i> is the row number and
+   * <i>jn</i> are the allocated columns in this row.
    */
   void print (std::ostream &out) const;
 
   /**
-   * Print the sparsity of the matrix
-   * in a format that <tt>gnuplot</tt> understands
-   * and which can be used to plot the
-   * sparsity pattern in a graphical
-   * way. The format consists of pairs
-   * <tt>i j</tt> of nonzero elements, each
-   * representing one entry of this
-   * matrix, one per line of the output
-   * file. Indices are counted from
-   * zero on, as usual. Since sparsity
-   * patterns are printed in the same
-   * way as matrices are displayed, we
-   * print the negative of the column
-   * index, which means that the
-   * <tt>(0,0)</tt> element is in the top left
-   * rather than in the bottom left
-   * corner.
+   * Print the sparsity of the matrix in a format that <tt>gnuplot</tt>
+   * understands and which can be used to plot the sparsity pattern in a
+   * graphical way. The format consists of pairs <tt>i j</tt> of nonzero
+   * elements, each representing one entry of this matrix, one per line of the
+   * output file. Indices are counted from zero on, as usual. Since sparsity
+   * patterns are printed in the same way as matrices are displayed, we print
+   * the negative of the column index, which means that the <tt>(0,0)</tt>
+   * element is in the top left rather than in the bottom left corner.
    *
-   * Print the sparsity pattern in
-   * gnuplot by setting the data style
-   * to dots or points and use the
-   * <tt>plot</tt> command.
+   * Print the sparsity pattern in gnuplot by setting the data style to dots
+   * or points and use the <tt>plot</tt> command.
    */
   void print_gnuplot (std::ostream &out) const;
+
   /**
-   * Write the data of this object to
-   * a stream for the purpose of serialization
+   * 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 serialization
+   * Read the data of this object from a stream for the purpose of
+   * serialization
    */
   template <class Archive>
   void load (Archive &ar, const unsigned int version);
@@ -1269,123 +914,80 @@ public:
    */
 // @{
   /**
-   * @deprecated
-   * This function is deprecated. Use
-   * SparsityTools::partition instead.
-   *
-   * Use the METIS partitioner to generate
-   * a partitioning of the degrees of
-   * freedom represented by this sparsity
-   * pattern. In effect, we view this
-   * sparsity pattern as a graph of
-   * connections between various degrees of
-   * freedom, where each nonzero entry in
-   * the sparsity pattern corresponds to an
-   * edge between two nodes in the
-   * connection graph. The goal is then to
-   * decompose this graph into groups of
-   * nodes so that a minimal number of
-   * edges are cut by the boundaries
-   * between node groups. This partitioning
-   * is done by METIS. Note that METIS can
-   * only partition symmetric sparsity
-   * patterns, and that of course the
-   * sparsity pattern has to be square. We
-   * do not check for symmetry of the
-   * sparsity pattern, since this is an
-   * expensive operation, but rather leave
-   * this as the responsibility of caller
-   * of this function.
-   *
-   * After calling this function, the
-   * output array will have values between
-   * zero and @p n_partitions-1 for each
-   * node (i.e. row or column of the
+   * @deprecated This function is deprecated. Use SparsityTools::partition
+   * instead.
+   *
+   * Use the METIS partitioner to generate a partitioning of the degrees of
+   * freedom represented by this sparsity pattern. In effect, we view this
+   * sparsity pattern as a graph of connections between various degrees of
+   * freedom, where each nonzero entry in the sparsity pattern corresponds to
+   * an edge between two nodes in the connection graph. The goal is then to
+   * decompose this graph into groups of nodes so that a minimal number of
+   * edges are cut by the boundaries between node groups. This partitioning is
+   * done by METIS. Note that METIS can only partition symmetric sparsity
+   * patterns, and that of course the sparsity pattern has to be square. We do
+   * not check for symmetry of the sparsity pattern, since this is an
+   * expensive operation, but rather leave this as the responsibility of
+   * caller of this function.
+   *
+   * After calling this function, the output array will have values between
+   * zero and @p n_partitions-1 for each node (i.e. row or column of the
    * matrix).
    *
-   * This function will generate an error
-   * if METIS is not installed unless
-   * @p n_partitions is one. I.e., you can
-   * write a program so that it runs in the
-   * single-processor single-partition case
-   * without METIS installed, and only
-   * requires METIS when multiple
-   * partitions are required.
+   * This function will generate an error if METIS is not installed unless @p
+   * n_partitions is one. I.e., you can write a program so that it runs in the
+   * single-processor single-partition case without METIS installed, and only
+   * requires METIS when multiple partitions are required.
    *
-   * Note that the sparsity pattern itself
-   * is not changed by calling this
-   * function. However, you will likely use
-   * the information generated by calling
-   * this function to renumber degrees of
-   * freedom, after which you will of
-   * course have to regenerate the sparsity
-   * pattern.
+   * Note that the sparsity pattern itself is not changed by calling this
+   * function. However, you will likely use the information generated by
+   * calling this function to renumber degrees of freedom, after which you
+   * will of course have to regenerate the sparsity pattern.
    *
-   * This function will rarely be called
-   * separately, since in finite element
-   * methods you will want to partition the
-   * mesh, not the matrix. This can be done
-   * by calling
-   * @p GridTools::partition_triangulation.
+   * This function will rarely be called separately, since in finite element
+   * methods you will want to partition the mesh, not the matrix. This can be
+   * done by calling @p GridTools::partition_triangulation.
    */
   void partition (const unsigned int         n_partitions,
                   std::vector<unsigned int> &partition_indices) const;
 
 
   /**
-   * @deprecated This is kind of an expert mode. Get
-   * access to the rowstart array, but
-   * read-only.
+   * @deprecated This is kind of an expert mode. Get access to the rowstart
+   * array, but read-only.
    *
-   * Use of this function is highly
-   * deprecated. Use @p row_length and
-   * @p column_number instead. Also, using
-   * iterators may get you most of the
+   * Use of this function is highly deprecated. Use @p row_length and @p
+   * column_number instead. Also, using iterators may get you most of the
    * information you may want.
    *
-   * Though the return value is declared
-   * <tt>const</tt>, you should be aware that it
-   * may change if you call any nonconstant
-   * function of objects which operate on
-   * it.
+   * Though the return value is declared <tt>const</tt>, you should be aware
+   * that it may change if you call any nonconstant function of objects which
+   * operate on it.
    *
-   * You should use this interface very
-   * carefully and only if you are absolutely
-   * sure to know what you do. You should
-   * also note that the structure of these
-   * arrays may change over time.
-   * If you change the layout yourself, you
-   * should also rename this function to
-   * avoid programs relying on outdated
-   * information!
+   * You should use this interface very carefully and only if you are
+   * absolutely sure to know what you do. You should also note that the
+   * structure of these arrays may change over time.  If you change the layout
+   * yourself, you should also rename this function to avoid programs relying
+   * on outdated information!
    */
   inline const std::size_t *get_rowstart_indices () const;
 
   /**
-   * @deprecated. Use @p row_length and
-   * @p column_number instead. Also, using
-   * iterators may get you most of the
-   * information you may want.
+   * @deprecated. Use @p row_length and @p column_number instead. Also, using
+   * iterators may get you most of the information you may want.
    *
-   * This is kind of an expert mode: get
-   * access to the colnums array, but
+   * This is kind of an expert mode: get access to the colnums array, but
    * readonly.
    *
-   * Though the return value is declared
-   * <tt>const</tt>, you should be aware that it
-   * may change if you call any nonconstant
-   * function of objects which operate on
-   * it.
+   * Though the return value is declared <tt>const</tt>, you should be aware
+   * that it may change if you call any nonconstant function of objects which
+   * operate on it.
    *
-   * You should use this interface very
-   * carefully and only if you are absolutely
-   * sure to know what you do. You should
-   * also note that the structure of these
-   * arrays may change over time.
-   * If you change the layout yourself, you
-   * should also rename this function to
-   * avoid programs relying on outdated
-   * information!
+   * You should use this interface very carefully and only if you are
+   * absolutely sure to know what you do. You should also note that the
+   * structure of these arrays may change over time. If you change the layout
+   * yourself, you should also rename this function to avoid programs relying
+   * on outdated information!
    */
   inline const unsigned int *get_column_numbers () const;
 
@@ -1394,8 +996,7 @@ public:
    * @name Exceptions
    * @{ */
   /**
-   * You tried to add an element to
-   * a row, but there was no space left.
+   * You tried to add an element to a row, but there was no space left.
    */
   DeclException2 (ExcNotEnoughSpace,
                   int, int,
@@ -1404,18 +1005,13 @@ public:
                   << "(Maximum number of entries for this row: "
                   << arg2 << "; maybe the matrix is already compressed?)");
   /**
-   * The operation is only allowed
-   * after the SparsityPattern has
-   * been set up and compress() was
-   * called.
+   * The operation is only allowed after the SparsityPattern has been set up
+   * and compress() was called.
    */
   DeclException0 (ExcNotCompressed);
   /**
-   * This operation changes the
-   * structure of the
-   * SparsityPattern and is not
-   * possible after compress() has
-   * been called.
+   * This operation changes the structure of the SparsityPattern and is not
+   * possible after compress() has been called.
    */
   DeclException0 (ExcMatrixIsCompressed);
   /**
@@ -1423,13 +1019,9 @@ public:
    */
   DeclException0 (ExcInvalidConstructorCall);
   /**
-   * This exception is thrown if
-   * the matrix does not follow the
-   * convention of storing diagonal
-   * elements first in row. Refer
-   * to
-   * SparityPattern::optimize_diagonal()
-   * for more information.
+   * This exception is thrown if the matrix does not follow the convention of
+   * storing diagonal elements first in row. Refer to
+   * SparityPattern::optimize_diagonal() for more information.
    */
   DeclException0 (ExcDiagonalNotOptimized);
   /**
@@ -1449,149 +1041,91 @@ public:
   //@}
 private:
   /**
-   * Maximum number of rows that can
-   * be stored in the #rowstart array.
-   * Since reallocation of that array
-   * only happens if the present one is
-   * too small, but never when the size
-   * of this matrix structure shrinks,
-   * #max_dim might be larger than
-   * #rows and in this case #rowstart
-   * has more elements than are used.
+   * Maximum number of rows that can be stored in the #rowstart array.  Since
+   * reallocation of that array only happens if the present one is too small,
+   * but never when the size of this matrix structure shrinks, #max_dim might
+   * be larger than #rows and in this case #rowstart has more elements than
+   * are used.
    */
   unsigned int max_dim;
 
   /**
-   * Number of rows that this sparsity
-   * structure shall represent.
+   * Number of rows that this sparsity structure shall represent.
    */
   unsigned int rows;
 
   /**
-   * Number of columns that this sparsity
-   * structure shall represent.
+   * Number of columns that this sparsity structure shall represent.
    */
   unsigned int cols;
 
   /**
-   * Size of the actually allocated array
-   * #colnums. Here, the same applies as
-   * for the #rowstart array, i.e. it
-   * may be larger than the actually used
+   * Size of the actually allocated array #colnums. Here, the same applies as
+   * for the #rowstart array, i.e. it may be larger than the actually used
    * part of the array.
    */
   std::size_t max_vec_len;
 
   /**
-   * Maximum number of elements per
-   * row. This is set to the value
-   * given to the reinit() function
-   * (or to the constructor), or to
-   * the maximum row length
-   * computed from the vectors in
-   * case the more flexible
-   * constructors or reinit
-   * versions are called. Its value
-   * is more or less meaningless
-   * after compress() has been
-   * called.
+   * Maximum number of elements per row. This is set to the value given to the
+   * reinit() function (or to the constructor), or to the maximum row length
+   * computed from the vectors in case the more flexible constructors or
+   * reinit versions are called. Its value is more or less meaningless after
+   * compress() has been called.
    */
   unsigned int max_row_length;
 
   /**
-   * Array which hold for each row
-   * which is the first element in
-   * #colnums belonging to that
-   * row. Note that the size of the
-   * array is one larger than the
-   * number of rows, because the
-   * last element is used for
-   * <tt>row</tt>=#rows, i.e. the
-   * row past the last used
-   * one. The value of
-   * #rowstart[#rows]} equals the
-   * index of the element past the
-   * end in #colnums; this way, we
-   * are able to write loops like
-   * <tt>for (i=rowstart[k];
-   * i<rowstart[k+1]; ++i)</tt>
-   * also for the last row.
+   * Array which hold for each row which is the first element in #colnums
+   * belonging to that row. Note that the size of the array is one larger than
+   * the number of rows, because the last element is used for
+   * <tt>row</tt>=#rows, i.e. the row past the last used one. The value of
+   * #rowstart[#rows]} equals the index of the element past the end in
+   * #colnums; this way, we are able to write loops like <tt>for
+   * (i=rowstart[k]; i<rowstart[k+1]; ++i)</tt> also for the last row.
    *
-   * Note that the actual size of the
-   * allocated memory may be larger than
-   * the region that is used. The actual
-   * number of elements that was allocated
-   * is stored in #max_dim.
+   * Note that the actual size of the allocated memory may be larger than the
+   * region that is used. The actual number of elements that was allocated is
+   * stored in #max_dim.
    */
   std::size_t *rowstart;
 
   /**
-   * Array of column numbers. In
-   * this array, we store for each
-   * non-zero element its column
-   * number. The column numbers for
-   * the elements in row <i>r</i>
-   * are stored within the index
-   * range
-   * #rowstart[<i>r</i>]...#rowstart[<i>r+1</i>]. Therefore
-   * to find out whether a given
-   * element (<i>r,c</i>) exists,
-   * we have to check whether the
-   * column number <i>c</i> exists
-   * in the abovementioned range
-   * within this array. If it
-   * exists, say at position
-   * <i>p</i> within this array,
-   * the value of the respective
-   * element in the sparse matrix
-   * will also be at position
-   * <i>p</i> of the values array
-   * of that class.
-   *
-   * At the beginning, all elements
-   * of this array are set to
-   * @p -1 indicating invalid
-   * (unused) column numbers
-   * (diagonal elements are preset
-   * if optimized storage is
-   * requested, though). Now, if
-   * nonzero elements are added,
-   * one column number in the row's
-   * respective range after the
-   * other is set to the column
-   * number of the added
-   * element. When compress is
-   * called, unused elements
-   * (indicated by column numbers
-   * @p -1) are eliminated by
-   * copying the column number of
-   * subsequent rows and the column
-   * numbers within each row (with
-   * possible exception of the
-   * diagonal element) are sorted,
-   * such that finding whether an
-   * element exists and determining
-   * its position can be done by a
-   * binary search.
+   * Array of column numbers. In this array, we store for each non-zero
+   * element its column number. The column numbers for the elements in row
+   * <i>r</i> are stored within the index range
+   * #rowstart[<i>r</i>]...#rowstart[<i>r+1</i>]. Therefore to find out
+   * whether a given element (<i>r,c</i>) exists, we have to check whether the
+   * column number <i>c</i> exists in the abovementioned range within this
+   * array. If it exists, say at position <i>p</i> within this array, the
+   * value of the respective element in the sparse matrix will also be at
+   * position <i>p</i> of the values array of that class.
+   *
+   * At the beginning, all elements of this array are set to @p -1 indicating
+   * invalid (unused) column numbers (diagonal elements are preset if
+   * optimized storage is requested, though). Now, if nonzero elements are
+   * added, one column number in the row's respective range after the other is
+   * set to the column number of the added element. When compress is called,
+   * unused elements (indicated by column numbers @p -1) are eliminated by
+   * copying the column number of subsequent rows and the column numbers
+   * within each row (with possible exception of the diagonal element) are
+   * sorted, such that finding whether an element exists and determining its
+   * position can be done by a binary search.
    */
   unsigned int *colnums;
 
   /**
-   * Store whether the compress()
-   * function was called for this
-   * object.
+   * Store whether the compress() function was called for this object.
    */
   bool compressed;
 
   /**
-   * Is special treatment of
-   * diagonals enabled?
+   * Is special treatment of diagonals enabled?
    */
   bool diagonal_optimized;
 
   /**
-   * Make all sparse matrices
-   * friends of this class.
+   * Make all sparse matrices friends of this class.
    */
   template <typename number> friend class SparseMatrix;
   template <typename number> friend class ChunkSparseMatrix;
@@ -1707,16 +1241,14 @@ namespace SparsityPatternIterators
 
     ++a_index;
 
-    // if at end of line: cycle until we
-    // find a row with a nonzero number of
+    // if at end of line: cycle until we find a row with a nonzero number of
     // entries
     while (a_index >= sparsity_pattern->row_length(a_row))
       {
         a_index = 0;
         ++a_row;
 
-        // if we happened to find the end
-        // of the matrix, then stop here
+        // if we happened to find the end of the matrix, then stop here
         if (a_row == sparsity_pattern->n_rows())
           break;
       }
@@ -1804,14 +1336,12 @@ inline
 SparsityPattern::iterator
 SparsityPattern::begin () const
 {
-  // search for the first line with a nonzero
-  // number of entries
+  // search for the first line with a nonzero number of entries
   for (unsigned int r=0; r<n_rows(); ++r)
     if (row_length(r) > 0)
       return iterator(this, r, 0);
 
-  // alright, this matrix is completely
-  // empty. that's strange but ok. simply
+  // alright, this matrix is completely empty. that's strange but ok. simply
   // return the end() iterator
   return end();
 }
@@ -1846,15 +1376,13 @@ SparsityPattern::end (const unsigned int r) const
 {
   Assert (r<n_rows(), ExcIndexRange(r,0,n_rows()));
 
-  // place the iterator on the first entry
-  // past this line, or at the end of the
-  // matrix
+  // place the iterator on the first entry past this line, or at the end of
+  // the matrix
   for (unsigned int i=r+1; i<n_rows(); ++i)
     if (row_length(i) > 0)
       return iterator(this, i, 0);
 
-  // if there is no such line, then take the
-  // end iterator of the matrix
+  // if there is no such line, then take the end iterator of the matrix
   return end();
 }
 
@@ -1980,8 +1508,7 @@ inline
 void
 SparsityPattern::save (Archive &ar, const unsigned int) const
 {
-  // forward to serialization
-  // function in the base class.
+  // forward to serialization function in the base class.
   ar   &static_cast<const Subscriptor &>(*this);
 
   ar &max_dim &rows &cols &max_vec_len &max_row_length &compressed &diagonal_optimized;
@@ -1997,8 +1524,7 @@ inline
 void
 SparsityPattern::load (Archive &ar, const unsigned int)
 {
-  // forward to serialization
-  // function in the base class.
+  // forward to serialization function in the base class.
   ar   &static_cast<Subscriptor &>(*this);
 
   ar &max_dim &rows &cols &max_vec_len &max_row_length &compressed &diagonal_optimized;
@@ -2016,15 +1542,10 @@ inline
 bool
 SparsityPattern::operator == (const SparsityPattern &sp2)  const
 {
-  // it isn't quite necessary to
-  // compare *all* member
-  // variables. by only comparing the
-  // essential ones, we can say that
-  // two sparsity patterns are equal
-  // even if one is compressed and
-  // the other is not (in which case
-  // some of the member variables are
-  // not yet set correctly)
+  // it isn't quite necessary to compare *all* member variables. by only
+  // comparing the essential ones, we can say that two sparsity patterns are
+  // equal even if one is compressed and the other is not (in which case some
+  // of the member variables are not yet set correctly)
   if (rows != sp2.rows ||
       cols != sp2.cols ||
       compressed != sp2.compressed ||
@@ -2090,16 +1611,10 @@ SparsityPattern::copy_from (const unsigned int    n_rows,
   Assert (static_cast<unsigned int>(std::distance (begin, end)) == n_rows,
           ExcIteratorRange (std::distance (begin, end), n_rows));
 
-  // first determine row lengths for
-  // each row. if the matrix is
-  // quadratic, then we might have to
-  // add an additional entry for the
-  // diagonal, if that is not yet
-  // present. as we have to call
-  // compress anyway later on, don't
-  // bother to check whether that
-  // diagonal entry is in a certain
-  // row or not
+  // first determine row lengths for each row. if the matrix is quadratic,
+  // then we might have to add an additional entry for the diagonal, if that
+  // is not yet present. as we have to call compress anyway later on, don't
+  // bother to check whether that diagonal entry is in a certain row or not
   const bool is_square = optimize_diag && (n_rows == n_cols);
   std::vector<unsigned int> row_lengths;
   row_lengths.reserve(n_rows);
@@ -2109,15 +1624,11 @@ SparsityPattern::copy_from (const unsigned int    n_rows,
                            (is_square ? 1 : 0));
   reinit (n_rows, n_cols, row_lengths, is_square);
 
-  // now enter all the elements into
-  // the matrix. note that if the
-  // matrix is quadratic, then we
-  // already have the diagonal
-  // element preallocated
+  // now enter all the elements into the matrix. note that if the matrix is
+  // quadratic, then we already have the diagonal element preallocated
   //
-  // for use in the inner loop, we
-  // define a typedef to the type of
-  // the inner iterators
+  // for use in the inner loop, we define a typedef to the type of the inner
+  // iterators
   unsigned int row = 0;
   typedef typename std::iterator_traits<ForwardIterator>::value_type::const_iterator inner_iterator;
   for (ForwardIterator i=begin; i!=end; ++i, ++row)
@@ -2135,9 +1646,7 @@ SparsityPattern::copy_from (const unsigned int    n_rows,
         };
     };
 
-  // finally compress
-  // everything. this also sorts the
-  // entries within each row
+  // finally compress everything. this also sorts the entries within each row
   compress ();
 }
 

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.