From: Wolfgang Bangerth <bangerth@math.tamu.edu>
Date: Mon, 8 Dec 2014 15:27:12 +0000 (-0600)
Subject: Clarify documentation.
X-Git-Tag: v8.2.0-rc1~28^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ac5fca2065249c55b131b5c07abcaa0e08d14932;p=dealii.git

Clarify documentation.
---

diff --git a/include/deal.II/numerics/data_out_dof_data.h b/include/deal.II/numerics/data_out_dof_data.h
index 7921495bba..e5e7a4ed6b 100644
--- a/include/deal.II/numerics/data_out_dof_data.h
+++ b/include/deal.II/numerics/data_out_dof_data.h
@@ -602,8 +602,9 @@ public:
 
   /**
    * This function is an alternative to the above ones, allowing the output of
-   * derived quantities instead of the given data. This converison has to be
-   * done in a class derived from DataPostprocessor.
+   * derived quantities instead of the given data. This conversion has to be
+   * done in a class derived from DataPostprocessor. This function is used in
+   * step-29. Other uses are shown in step-32 and step-33.
    *
    * The names for these derived quantities are provided by the @p
    * data_postprocessor argument. Likewise, the data_component_interpretation
@@ -617,6 +618,15 @@ public:
    * FEValuesBase::get_function_values() function. In particular, this
    * includes all of the usual vector types, but also IndexSet (see step-41
    * for a use of this).
+   *
+   * @note The DataPostprocessor object (i.e., in reality the object of your derived
+   * class) has to live until the DataOut object is destroyed as the latter keeps
+   * a pointer to the former and will complain if the object pointed to is
+   * destroyed while the latter still has a pointer to it. If both the data
+   * postprocessor and DataOut objects are local variables of a function
+   * (as they are, for example, in step-29), then you can avoid this
+   * error by declaring the data postprocessor variable before the DataOut
+   * variable as objects are destroyed in reverse order of declaration.
    */
   template <class VECTOR>
   void add_data_vector (const VECTOR                           &data,
diff --git a/include/deal.II/numerics/data_postprocessor.h b/include/deal.II/numerics/data_postprocessor.h
index 8c1e0b5bcc..1da010368c 100644
--- a/include/deal.II/numerics/data_postprocessor.h
+++ b/include/deal.II/numerics/data_postprocessor.h
@@ -46,11 +46,19 @@ DEAL_II_NAMESPACE_OPEN
  * points where we want to generated output, the functions of this class can
  * be overloaded to compute new quantities.
  *
- * A data vector and an object of a derived class can be given to the
- * DataOut::add_data_vector() function, which will write the derived
- * quantities instead of the provided data to the output file. Note, that the
- * DataPostprocessor has to live until DataOut::build_patches has been
- * called. DataOutFaces and DataOutRotation can be used as well.
+ * A data vector and an object of a class derived from the current one can
+ * be given to the DataOut::add_data_vector() function (and similarly for
+ * DataOutRotation and DataOutFaces). This will cause
+ * DataOut::build_patches() to compute the derived quantities instead of using
+ * the data provided by the data vector (typically the solution vector). Note
+ * that the DataPostprocessor object (i.e., in reality the object of your derived
+ * class) has to live until the DataOut object is destroyed as the latter keeps
+ * a pointer to the former and will complain if the object pointed to is
+ * destroyed while the latter still has a pointer to it. If both the data
+ * postprocessor and DataOut objects are local variables of a function
+ * (as they are, for example, in step-29), then you can avoid this
+ * error by declaring the data postprocessor variable before the DataOut
+ * variable as objects are destroyed in reverse order of declaration.
  *
  * In order not to perform needless calculations, DataPostprocessor
  * has to provide information which input data is needed for the