From f5e0d08ee8899a324e08cffd4854447811cc8133 Mon Sep 17 00:00:00 2001
From: Denis Davydov <davydden@gmail.com>
Date: Wed, 27 Sep 2017 10:34:53 +0200
Subject: [PATCH] minor documentation cleanup

---
 include/deal.II/lac/lapack_full_matrix.h | 24 +++++++++++++++++-------
 include/deal.II/lac/lapack_support.h     |  2 +-
 2 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/include/deal.II/lac/lapack_full_matrix.h b/include/deal.II/lac/lapack_full_matrix.h
index 6bf20a3a8f..a1a2c413a5 100644
--- a/include/deal.II/lac/lapack_full_matrix.h
+++ b/include/deal.II/lac/lapack_full_matrix.h
@@ -413,19 +413,29 @@ public:
   /**
    * Compute the Cholesky factorization of the matrix using LAPACK function Xpotrf.
    *
-   * @note The factorization is stored in the lower diagonal.
+   * @note The factorization is stored in the lower-triangular part of the matrix.
    */
   void compute_cholesky_factorization ();
 
   /**
-   * Estimate reciprocal of the condition number (in 1-norm) of a SPD matrix
-   * using Cholesky factorization. This function can only be called if the matrix
-   * is already factorized.
+   * Estimate the reciprocal of the condition number $1/k(A)$ in $L_1$ norm ($1/(||A||_1 ||A^{-1}||_1)$)
+   * of a symmetric positive definite matrix using Cholesky factorization. This function can only
+   * be called if the matrix is already factorized.
    *
-   * @param a_norm Is the 1-norm of the matrix before calling Cholesky
-   * factorization.
+   * @note The condition number $k(A)$ can be used to estimate the numerical
+   * error related to the matrix inversion or the solution of the
+   * system of linear algebraic equations as
+   * <code>error = std::numeric_limits<Number>::epsilon * k</code>.
+   * Alternatively one can get the number of accurate digits
+   * <code>std::floor(std::log10(k))</code>.
+   *
+   * @note The function computes reciprocal of the condition number to
+   * avoid possible overflow if the matrix is nearly singular.
+   *
+   * @param[in] l1_norm Is the $L_1$ norm of the matrix before calling Cholesky
+   * factorization. It can be obtained by calling l1_norm().
    */
-  number reciprocal_condition_number(const number a_norm) const;
+  number reciprocal_condition_number(const number l1_norm) const;
 
   /**
    * Compute the determinant of a matrix. As it requires the LU factorization of
diff --git a/include/deal.II/lac/lapack_support.h b/include/deal.II/lac/lapack_support.h
index 6b4032999a..aa9dd7c3c1 100644
--- a/include/deal.II/lac/lapack_support.h
+++ b/include/deal.II/lac/lapack_support.h
@@ -176,7 +176,7 @@ namespace LAPACKSupport
    * operation.
    */
   DeclException1(ExcProperty, Property,
-                 << "The function cannot be called while the "
+                 << "The function cannot be called with a "
                  << property_name(arg1)
                  << " matrix.");
 
-- 
2.39.5