Augment documentation somewhat.

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

diff --git a/deal.II/include/deal.II/grid/grid_tools.h b/deal.II/include/deal.II/grid/grid_tools.h
index 09377b3774ece0f65601e49fb391176e747b3126..d37f30ffe47bd2177a43f564e37ebded05ce0b31 100644 (file)
--- a/deal.II/include/deal.II/grid/grid_tools.h
+++ b/deal.II/include/deal.II/grid/grid_tools.h
@@ -184,14 +184,15 @@ namespace GridTools
    * pointer to the function. In
    * either case, argument and
    * return value have to be of
-   * type <tt>Point<spacedim></tt>.
+   * type <tt>Point@<spacedim@></tt>.
    *
-   * Note: if you are using a parallel::distributed::Triangulation you will have
+   * @note If you are using a parallel::distributed::Triangulation you will have
    * hanging nodes in your local Triangulation even if your "global" mesh has
    * no hanging nodes. This will cause issues with wrong positioning of hanging
-   * nodes in ghost cells. The active cells will be correct, but keep in mind that
-   * computations like KellyErrorEstimator will give wrong answers. A safe bet is
-   * to use this function prior to any refinement in parallel.
+   * nodes in ghost cells. The vertices of all locally owned cells will be correct,
+   * but the vertices of some ghost cells may not. This means that
+   * computations like KellyErrorEstimator may give wrong answers. A safe bet is
+   * to use this function prior to any refinement in parallel, if that is possible.
    *
    * This function is used in the
    * "Possibilities for extensions" section

diff --git a/deal.II/include/deal.II/grid/tria_accessor.h b/deal.II/include/deal.II/grid/tria_accessor.h
index 4a45fd4c5e2660546390ade10737c2575dd40b41..17e78fd2b7f7bc9cc1452a94015b2ccc014c0cac 100644 (file)
--- a/deal.II/include/deal.II/grid/tria_accessor.h
+++ b/deal.II/include/deal.II/grid/tria_accessor.h
@@ -777,7 +777,41 @@ public:
 
   /**
    *  Return a reference to the
-   *  @p ith vertex.
+   *  @p ith vertex. The reference is not const, i.e., it is possible
+   *  to call this function on the left hand side of an assignment,
+   *  thereby moving the vertex of a cell within the triangulation. Of
+   *  course, doing so requires that you ensure that the new location
+   *  of the vertex remains useful -- for example, avoiding inverted
+   *  or otherwise distorted (see also @ref GlossDistorted).
+   *
+   *  @note When a cell is refined, its children inherit the position
+   *  of the vertex positions of those vertices they share with the mother
+   *  cell (plus the locations of the new vertices on edges, faces, and
+   *  cell interiors that are created for the new child cells). If the
+   *  vertex of a cell is moved, this implies that its children will also
+   *  use these new locations. On the other hand, imagine a 2d situation
+   *  where you have one cell that is refined (with four children) and then
+   *  you move the central vertex connecting all four children. If you
+   *  coarsen these four children again to the mother cell, then the
+   *  location of the moved vertex is lost and if, in a later step, you
+   *  refine the mother cell again, the then again new vertex will be
+   *  placed again at the same position as the first time around -- i.e.,
+   *  not at the location you had previously moved it to.
+   *
+   *  @note The behavior described in the previous note is relevant if
+   *  you have a parallel::distributed::Triangulation object. There,
+   *  refining a mesh always involves a re-partitioning. In other words,
+   *  vertices of locally owned cells (see @ref GlossLocallyOwnedCell)
+   *  that you may have moved to a different location on one processor
+   *  may be moved to a different processor upon mesh refinement (even
+   *  if these particular cells were not refined) which will re-create
+   *  their position based on the position of the coarse cells they
+   *  previously had, not based on the position these vertices had on
+   *  the processor that previously owned them. In other words, in
+   *  parallel computations, you will probably have to move nodes
+   *  explicitly after every mesh refinement because vertex positions
+   *  may or may not be preserved across the re-partitioning that
+   *  accompanies mesh refinement.
    */
   Point<spacedim> &vertex (const unsigned int i) const;