From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Tue, 6 Feb 2024 23:38:16 +0000 (-0700)
Subject: Better document a funny construct.
X-Git-Tag: relicensing~66^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F16601%2Fhead;p=dealii.git

Better document a funny construct.
---

diff --git a/examples/step-31/step-31.cc b/examples/step-31/step-31.cc
index 788028c682..8a62a8cc57 100644
--- a/examples/step-31/step-31.cc
+++ b/examples/step-31/step-31.cc
@@ -232,11 +232,17 @@ namespace Step31
     // where the exception was generated.
     //
     // So rather than letting the exception propagate freely up to
-    // <code>main()</code> we realize that there is little that an outer
-    // function can do if the inner solver fails and rather convert the
-    // run-time exception into an assertion that fails and triggers a call to
-    // <code>abort()</code>, allowing us to trace back in a debugger how we
-    // got to the current place.
+    // <code>main()</code>, we acknowledge that in the current context
+    // there is little that an outer function can do if the inner
+    // solver fails. As a consequence, we deal with the situation by
+    // catching the exception and letting the program fail by
+    // triggering an assertion with a `false` condition (which of
+    // course always fails) and that uses the error message associated
+    // with the caught exception (returned by calling `e.what()`) as
+    // error text. In other words, instead of letting the error
+    // message be produced by `main()`, we rather report it here where
+    // we can abort the program preserving information about where the
+    // problem happened.
     template <class MatrixType, class PreconditionerType>
     class InverseMatrix : public Subscriptor
     {
diff --git a/examples/step-55/step-55.cc b/examples/step-55/step-55.cc
index 250b0556be..9123f4c22e 100644
--- a/examples/step-55/step-55.cc
+++ b/examples/step-55/step-55.cc
@@ -88,12 +88,15 @@ namespace Step55
 
   namespace LinearSolvers
   {
-    // This class exposes the action of applying the inverse of a giving
-    // matrix via the function InverseMatrix::vmult(). Internally, the
-    // inverse is not formed explicitly. Instead, a linear solver with CG
-    // is performed. This class extends the InverseMatrix class in step-22
-    // with an option to specify a preconditioner, and to allow for different
-    // vector types in the vmult function.
+    // This class exposes the action of applying the inverse of a
+    // giving matrix via the function
+    // InverseMatrix::vmult(). Internally, the inverse is not formed
+    // explicitly. Instead, a linear solver with CG is performed. This
+    // class extends the InverseMatrix class in step-22 with an option
+    // to specify a preconditioner, and to allow for different vector
+    // types in the vmult function. We use the same mechanism as in
+    // step-31 to convert a run-time exception into a failed assertion
+    // should the inner solver not converge.
     template <class Matrix, class Preconditioner>
     class InverseMatrix : public Subscriptor
     {