From: Matthias Maier <tamiko@43-1.org>
Date: Thu, 4 Feb 2021 20:48:26 +0000 (-0600)
Subject: Documentation: Advertise <deal.II/lac/linear_operator_tools.h>
X-Git-Tag: v9.3.0-rc1~504^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F11684%2Fhead;p=dealii.git

Documentation: Advertise <deal.II/lac/linear_operator_tools.h>

Let's add some pointers to linear_operator_tools.h for the reader.
Maybe this helps to clarify the situation.
---

diff --git a/doc/doxygen/headers/laoperators.h b/doc/doxygen/headers/laoperators.h
index 0e09e31a0b..d88a81437b 100644
--- a/doc/doxygen/headers/laoperators.h
+++ b/doc/doxygen/headers/laoperators.h
@@ -44,6 +44,8 @@
  * LinearOperator <code>op</code> that performs above computation when
  * applied on a vector, one can write:
  * @code
+ * #include <deal.II/lac/linear_operator_tools.h>
+ *
  * dealii::SparseMatrix<double> A, B, C;
  * double k;
  * // Setup and assembly...
@@ -116,6 +118,8 @@
  *
  * As an example consider the addition of multiple vectors:
  * @code
+ *   #include <deal.II/lac/linear_operator_tools.h>
+ *
  *   dealii::Vector<double> a, b, c, d;
  *   // ..
  *   dealii::Vector<double> result = a + b - c + d;
@@ -178,9 +182,16 @@
  *   Vector<double> residual =  b - op_a * x; // computes the residual at this point
  * @endcode
  *
- * The step-20 tutorial program has a detailed usage example of the
+ * @note The step-20 tutorial program has a detailed usage example of the
  * PackagedOperation class.
  *
+ * @note Many use cases of LinearOperator lead to intermediate expressions
+ * requiring a PackagedOperation. In order to include all necessary header
+ * files in one go consider using
+ * @code
+ * #include <deal.II/lac/linear_operator_tools.h>
+ * @endcode
+ *
  *
  * @ingroup LAC
  * @ingroup MATRICES
diff --git a/include/deal.II/lac/linear_operator.h b/include/deal.II/lac/linear_operator.h
index 726ac02564..8e45ec6684 100644
--- a/include/deal.II/lac/linear_operator.h
+++ b/include/deal.II/lac/linear_operator.h
@@ -113,6 +113,8 @@ identity_operator(const LinearOperator<Range, Domain, Payload> &);
  * one can write:
  *
  * @code
+ * #include <deal.II/lac/linear_operator_tools.h>
+ *
  * dealii::SparseMatrix<double> A, B, C;
  * const double k = ...;
  *
@@ -154,6 +156,15 @@ identity_operator(const LinearOperator<Range, Domain, Payload> &);
  * an interface that produces the result of this composite operation that is
  * compatible with Trilinos operator used by Trilinos solvers.
  *
+ * @note Many use cases of LinearOperator lead to intermediate expressions
+ * requiring a PackagedOperation. In order to include all necessary header
+ * files in one go consider using
+ * @code
+ * #include <deal.II/lac/linear_operator_tools.h>
+ * @endcode
+ *
+ * In order to use the full LinearOperator and PackagedOperation
+ *
  * @note To ensure that the correct payload is provided, wrapper functions
  * for linear operators have been provided within the respective
  * TrilinosWrappers (and, in the future, PETScWrappers) namespaces.