Minor updates to the documentation of GridTools::transform().

diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h
index ea340ebe04297c8d0cad39eeece8281d998a8b46..7b117ccac02759467d4ef7cae8a25de1d2cb3bc4 100644 (file)
--- a/include/deal.II/grid/grid_tools.h
+++ b/include/deal.II/grid/grid_tools.h
@@ -480,8 +480,9 @@ namespace GridTools
    * The transformation given as argument is used to transform each vertex.
    * Its respective type has to offer a function-like syntax, i.e. the
    * predicate is either an object of a type that has an <tt>operator()</tt>,
-   * or it is a pointer to the function. In either case, argument and return
-   * value have to be of type <tt>Point@<spacedim@></tt>.
+   * or it is a pointer to a non-member function, or it is a lambda function
+   * object. In either case, argument and return
+   * value have to be of type `Point@<spacedim@>`.
    *
    * @note The transformations that make sense to use with this function
    *   should have a Jacobian with a positive determinant. For example,
@@ -506,20 +507,28 @@ namespace GridTools
    * to the triangulation. For example, in order to refine the grid (using
    * manifolds) after the grid transformation, you have to make sure that
    * the original manifold is still valid for the transformed geometry. This
-   * does not hold in general, and it is necessary to clear the manifold and
-   * attach a new one for the transformed geometry in these cases.
-   * If you want to perform refinements according to the original
-   * manifold description attached to the triangulation, you should first do
-   * the refinements, subsequently deactivate all manifolds, and finally call
-   * the transform() function. The result is a triangulation with correctly
-   * transformed vertices, but otherwise straight-sided elements. The
-   * following procedure is recommended
+   * does not hold in general, and it is necessary to clear manifolds from
+   * the triangulation (for example, using Triangulation::clear_all_manifolds())
+   * before the transformation, and then attach new ones after the
+   * transformation that are valid for the transformed geometry. There are cases
+   * where this is awkward, most notably if you are using a mesh generated by
+   * the functions in GridGenerator which generally attach suitable manifolds
+   * upon mesh generation; in those cases, you will have to think about how
+   * these manifolds were constructed, and create a manifold that is constructed
+   * in a similar way but applies to the transformed geometry. As a consequence,
+   * if you only care about manifolds for mesh refinement, it is often simpler
+   * to just refine the original mesh before transformation as needed, and then
+   * simply forget about the manifolds. Of course, manifolds are also used for
+   * other cases (e.g., for normal vectors, curved edges and faces, and higher
+   * order mappings), and if these are relevant to what you are doing, then
+   * there is no alternative to building appropriate manifolds for the
+   * transformed geometry and attaching these to the transformed geometry. In
+   * general, detaching manifolds from a triangulation and then doing the
+   * transformation would look as follows:
    * @code
    * ...
-   * triangulation.refine_global(n_refinements);
    * triangulation.reset_all_manifolds();
-   * Transformation<dim> transformation;
-   * GridTools::transform(transformation, triangulation);
+   * GridTools::transform(MyTransformation<dim>(), triangulation);
    * ...
    * @endcode
    *
@@ -534,7 +543,8 @@ namespace GridTools
   /**
    * Shift each vertex of the triangulation by the given shift vector. This
    * function uses the transform() function above, so the requirements on the
-   * triangulation stated there hold for this function as well.
+   * triangulation stated there hold for this function as well; in particular,
+   * this is true about the discussion about manifolds.
    */
   template <int dim, int spacedim>
   void
@@ -547,7 +557,8 @@ namespace GridTools
    * counter-clockwise sense around the origin of the coordinate system by the
    * given angle (given in radians, rather than degrees). This function uses
    * the transform() function above, so the requirements on the triangulation
-   * stated there hold for this function as well.
+   * stated there hold for this function as well; in particular,
+   * this is true about the discussion about manifolds.
    *
    * @note This function is only supported for dim=2.
    */
@@ -558,7 +569,8 @@ namespace GridTools
   /**
    * Rotate all vertices of the given @p triangulation in counter-clockwise
    * direction around the @p axis described by a unit vector. Otherwise like the
-   * function above.
+   * function above; in particular, this function calls the transform() function
+   * and so the discussion about manifolds there also applies here.
    *
    * @param[in] angle Angle in radians to rotate the Triangulation by.
    * @param[in] axis A unit vector that defines the axis of rotation.
@@ -575,7 +587,8 @@ namespace GridTools
   /**
    * Rotate all vertices of the given @p triangulation in counter-clockwise
    * direction around the axis with the given index. Otherwise like the
-   * function above.
+   * function above; in particular, this function calls the transform() function
+   * and so the discussion about manifolds there also applies here.
    *
    * @param[in] angle Angle in radians to rotate the Triangulation by.
    * @param[in] axis Index of the coordinate axis to rotate around, keeping