From 893486ea6574647deb226387fb25d6c63a57e7a8 Mon Sep 17 00:00:00 2001
From: Wolfgang Bangerth <bangerth@math.tamu.edu>
Date: Fri, 14 Feb 2014 19:46:35 +0000
Subject: [PATCH] Add some documentation.

git-svn-id: https://svn.dealii.org/trunk@32490 0785d39b-7218-0410-832d-ea1e28bc413d
---
 deal.II/include/deal.II/lac/matrix_lib.h     | 49 +++++++++++++-------
 deal.II/include/deal.II/lac/pointer_matrix.h | 16 +++----
 2 files changed, 40 insertions(+), 25 deletions(-)

diff --git a/deal.II/include/deal.II/lac/matrix_lib.h b/deal.II/include/deal.II/lac/matrix_lib.h
index 2a438f0271..589ea82620 100644
--- a/deal.II/include/deal.II/lac/matrix_lib.h
+++ b/deal.II/include/deal.II/lac/matrix_lib.h
@@ -38,9 +38,12 @@ template<typename number> class SparseMatrix;
  * quadratic matrices #m1 and #m2 of arbitrary types and implements
  * matrix-vector multiplications for the product
  * <i>M<sub>1</sub>M<sub>2</sub></i> by performing multiplication with
- * both factors consecutively.
+ * both factors consecutively. Because the types of the matrices are
+ * opaque (i.e., they can be arbitrary), you can stack products of three
+ * or more matrices by making one of the two matrices an object of the
+ * current type handles be a ProductMatrix itself.
  *
- * Here an example multiplying two different FullMatrix objects:
+ * Here is an example multiplying two different FullMatrix objects:
  * @include product_matrix.cc
  *
  * @author Guido Kanschat, 2000, 2001, 2002, 2005
@@ -75,6 +78,11 @@ public:
                 const MATRIX2 &m2,
                 VectorMemory<VECTOR> &mem);
 
+  /**
+   * Destructor.
+   */
+  ~ProductMatrix();
+
   /**
    * Change the matrices.
    */
@@ -88,11 +96,6 @@ public:
   void initialize(const MATRIX1 &m1, const MATRIX2 &m2,
                   VectorMemory<VECTOR> &mem);
 
-  /**
-   * Destructor.
-   */
-  ~ProductMatrix();
-
   // Doc in PointerMatrixBase
   void clear();
 
@@ -104,7 +107,7 @@ public:
                       const VECTOR &v) const;
 
   /**
-   * Tranposed matrix-vector
+   * Transposed matrix-vector
    * product <i>w = m2<sup>T</sup> *
    * m1<sup>T</sup> * v</i>.
    */
@@ -119,7 +122,7 @@ public:
                           const VECTOR &v) const;
 
   /**
-   * Adding, tranposed
+   * Adding, transposed
    * matrix-vector product <i>w +=
    * m2<sup>T</sup> *
    * m1<sup>T</sup> * v</i>.
@@ -142,6 +145,7 @@ private:
    * Memory for auxiliary vector.
    */
   SmartPointer<VectorMemory<VECTOR>,ProductMatrix<VECTOR> > mem;
+
   /**
    * Return some kind of
    * identifier.
@@ -151,10 +155,11 @@ private:
 
 
 /**
- * A matrix that is the scaled version of another matrix.
+ * A matrix that is the multiple of another matrix.
  *
  * Matrix-vector products of this matrix are composed of those of the
- * original matrix and scaling by a constant factor.
+ * original matrix with the vector and then scaling of the result by
+ * a constant factor.
  *
  * @author Guido Kanschat, 2007
  */
@@ -252,7 +257,7 @@ public:
 
   /**
    * Constructor leaving an
-   * unitialized
+   * uninitialized
    * matrix. initialize() must be
    * called, before the matrix can
    * be used.
@@ -274,7 +279,7 @@ public:
                       const VectorType &v) const;
 
   /**
-   * Tranposed matrix-vector
+   * Transposed matrix-vector
    * product <i>w = m2<sup>T</sup> *
    * m1<sup>T</sup> * v</i>.
    */
@@ -289,7 +294,7 @@ public:
                           const VectorType &v) const;
 
   /**
-   * Adding, tranposed
+   * Adding, transposed
    * matrix-vector product <i>w +=
    * m2<sup>T</sup> *
    * m1<sup>T</sup> * v</i>.
@@ -326,6 +331,16 @@ private:
  * BlockVector, then an additional parameter selects a single
  * component for this operation.
  *
+ * In mathematical terms, this class acts as if it was the matrix
+ * $I-\frac 1n{\mathbf 1}_n{\mathbf 1}_n^T$ where ${\mathbf 1}_n$ is
+ * a vector of size $n$ that has only ones as its entries. Thus,
+ * taking the dot product between a vector $\mathbf v$ and
+ * $\frac 1n {\mathbf 1}_n$ yields the <i>mean value</i> of the entries
+ * of ${\mathbf v}$. Consequently,
+ * $ \left[I-\frac 1n{\mathbf 1}_n{\mathbf 1}_n^T\right] \mathbf v
+ * = \mathbf v - \left[\frac 1n \mathbf v} \cdot {\mathbf 1}_n\right]{\mathbf 1}_n$
+ * subtracts from every vector element the mean value of all elements.
+ *
  * @author Guido Kanschat, 2002, 2003
  */
 class MeanValueFilter : public Subscriptor
@@ -340,7 +355,7 @@ public:
    * Constructor, optionally
    * selecting a component.
    */
-  MeanValueFilter(size_type component = numbers::invalid_size_type);
+  MeanValueFilter(const size_type component = numbers::invalid_size_type);
 
   /**
    * Subtract mean value from @p v.
@@ -405,7 +420,7 @@ private:
   /**
    * Component for filtering block vectors.
    */
-  size_type component;
+  const size_type component;
 };
 
 
@@ -416,7 +431,7 @@ private:
  * SolverRichardson::Tsolve() allows for the implementation of
  * transpose matrix vector products.
  *
- * The functions vmult() and Tvmult() appoximate the inverse
+ * The functions vmult() and Tvmult() approximate the inverse
  * iteratively starting with the vector <tt>dst</tt>. Functions
  * vmult_add() and Tvmult_add() start the iteration with a zero
  * vector.
diff --git a/deal.II/include/deal.II/lac/pointer_matrix.h b/deal.II/include/deal.II/lac/pointer_matrix.h
index 6c0d5ca692..b53d6bab4b 100644
--- a/deal.II/include/deal.II/lac/pointer_matrix.h
+++ b/deal.II/include/deal.II/lac/pointer_matrix.h
@@ -127,7 +127,7 @@ public:
                       const VECTOR &src) const = 0;
 
   /**
-   * Tranposed matrix-vector product.
+   * Transposed matrix-vector product.
    */
   virtual void Tvmult (VECTOR &dst,
                        const VECTOR &src) const = 0;
@@ -140,7 +140,7 @@ public:
                           const VECTOR &src) const = 0;
 
   /**
-   * Tranposed matrix-vector product,
+   * Transposed matrix-vector product,
    * adding to <tt>dst</tt>.
    */
   virtual void Tvmult_add (VECTOR &dst,
@@ -222,7 +222,7 @@ public:
                       const VECTOR &src) const;
 
   /**
-   * Tranposed matrix-vector product.
+   * Transposed matrix-vector product.
    */
   virtual void Tvmult (VECTOR &dst,
                        const VECTOR &src) const;
@@ -235,7 +235,7 @@ public:
                           const VECTOR &src) const;
 
   /**
-   * Tranposed matrix-vector product,
+   * Transposed matrix-vector product,
    * adding to <tt>dst</tt>.
    */
   virtual void Tvmult_add (VECTOR &dst,
@@ -344,7 +344,7 @@ public:
                       const VECTOR &src) const;
 
   /**
-   * Tranposed matrix-vector product.
+   * Transposed matrix-vector product.
    */
   virtual void Tvmult (VECTOR &dst,
                        const VECTOR &src) const;
@@ -357,7 +357,7 @@ public:
                           const VECTOR &src) const;
 
   /**
-   * Tranposed matrix-vector product,
+   * Transposed matrix-vector product,
    * adding to <tt>dst</tt>.
    */
   virtual void Tvmult_add (VECTOR &dst,
@@ -468,7 +468,7 @@ public:
                       const Vector<number> &src) const;
 
   /**
-   * Tranposed matrix-vector
+   * Transposed matrix-vector
    * product, actually the
    * multiplication of the vector
    * representing this matrix with
@@ -497,7 +497,7 @@ public:
                           const Vector<number> &src) const;
 
   /**
-   * Tranposed matrix-vector product,
+   * Transposed matrix-vector product,
    * adding to <tt>dst</tt>.
    *
    * The dimension of <tt>src</tt>
-- 
2.39.5