More docs.

git-svn-id: https://svn.dealii.org/trunk@3256 0785d39b-7218-0410-832d-ea1e28bc413d

diff --git a/deal.II/deal.II/include/numerics/data_out_rotation.h b/deal.II/deal.II/include/numerics/data_out_rotation.h
index e49e215b6e8e0eae69676edf41baccddcc6a52c1..97a6a281f877822fc103af6ff7bcb778afbf00be 100644 (file)
--- a/deal.II/deal.II/include/numerics/data_out_rotation.h
+++ b/deal.II/deal.II/include/numerics/data_out_rotation.h
@@ -21,7 +21,53 @@
 
 template <int dim> class DoFHandler;
 
+
 /**
+ * This class generates output in the full domain of computations that
+ * were done using rotational symmetry of domain and solution. In
+ * particular, if a computation of a three dimensional problem with
+ * rotational symmetry around the @p{z}-axis (i.e. in the
+ * @p{r-z}-plane) was done, then this class can be used to generate
+ * the output in the original @p{x-y-z} space. In order to do so, it
+ * generates from each cell in the computational mesh a cell in the
+ * space with dimension one greater than that of the DoFHandler
+ * object. The resulting output will then consist of hexahedra forming
+ * an object that has rotational symmetry around the z-axis. As most
+ * graphical programs can not represent ring-like structures, the
+ * angular (rotation) variable is discretized into a finite number of
+ * intervals as well; the number of these intervals must be given to
+ * the @p{build_patches} function. It is noted, however, that while
+ * this function generates nice pictures of the whole domain, it often
+ * produces @em{very} large output files.
+ *
+ *
+ * @sect3{Interface}
+ *
+ * The interface of this class is copied from the @ref{DataOut}
+ * class. Furthermore, they share the common parent class
+ * @ref{DataOut_DoFData}. See the reference of these two classes for a
+ * discussion of the interface and how to extend it by deriving
+ * further classes from this class.
+ *
+ *
+ * @sect3{Details for 1d computations}
+ *
+ * Presently not implemented, sorry.
+ *
+ *
+ * @sect3{Details for 2d computations}
+ *
+ * We consider the computation (represented by the @ref{DoFHandler}
+ * object that is attached to this class) to have happened in the
+ * @p{r-z}-plane, where @p{r} is the radial variable and @p{z} denotes
+ * the axis of revolution around which the solution is symmetric. The
+ * output is in @p{x-y-z} space, where the radial dependence is
+ * transformed to the @p{x-y} plane. At present, it is not possible to
+ * exchange the meaning of the first and second variable of the plane
+ * in which the simulation was made, i.e. generate output from a
+ * simulation where the first variable denoted the symmetry axis, and
+ * the second denoted the radial variable. You have to take that into
+ * account when first programming your application.
  *
  * @author Wolfgang Bangerth, 2000
  */
@@ -30,13 +76,24 @@ class DataOutRotation : public DataOut_DoFData<dim,dim+1>
 {
   public:
                                     /**
-                                     * This is the central function of
-                                     * this class since it builds the list of
-                                     * patches to be written by the low-level
-                                     * functions of the base class. See the
-                                     * general documentation of this class
+                                     * This is the central function
+                                     * of this class since it builds
+                                     * the list of patches to be
+                                     * written by the low-level
+                                     * functions of the base
+                                     * class. See the general
+                                     * documentation of this class
                                      * for further information.
                                      *
+                                     * In addition to the same
+                                     * parameters as found in the
+                                     * respective function of the
+                                     * @ref{DataOut} class, the first
+                                     * parameter denotes into how
+                                     * many intervals the angular
+                                     * (rotation) variable is to be
+                                     * subdivided.
+                                     *
                                      * The function supports
                                      * multithreading, if deal.II is
                                      * compiled in multithreading
@@ -52,10 +109,10 @@ class DataOutRotation : public DataOut_DoFData<dim,dim+1>
                                     /**
                                      * Return the first cell which we
                                      * want output for. The default
-                                     * implementation returns the first
-                                     * active cell, but you might want
-                                     * to return other cells in a derived
-                                     * class.
+                                     * implementation returns the
+                                     * first active cell, but you
+                                     * might want to return other
+                                     * cells in a derived class.
                                      */
     virtual typename DoFHandler<dim>::cell_iterator
     first_cell ();
@@ -71,7 +128,6 @@ class DataOutRotation : public DataOut_DoFData<dim,dim+1>
                                      * active cell, but you might want
                                      * to return other cells in a derived
                                      * class. Note that the default
-
                                      * implementation assumes that
                                      * the given @p{cell} is active, which
                                      * is guaranteed as long as @p{first_cell}