From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Fri, 20 Sep 2019 23:10:42 +0000 (-0600)
Subject: Better document parallel::DistributedTriangulationBase.
X-Git-Tag: v9.2.0-rc1~1062^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F8822%2Fhead;p=dealii.git

Better document parallel::DistributedTriangulationBase.
---

diff --git a/include/deal.II/distributed/tria_base.h b/include/deal.II/distributed/tria_base.h
index 53749beb99..b7cd177894 100644
--- a/include/deal.II/distributed/tria_base.h
+++ b/include/deal.II/distributed/tria_base.h
@@ -246,10 +246,48 @@ namespace parallel
   template <int dim, int spacedim = dim>
   using Triangulation DEAL_II_DEPRECATED = TriangulationBase<dim, spacedim>;
 
+
+
   /**
-   * A base class for distributed triangulations. It can be used to test
-   * (via <tt>dynamic_cast</tt>) whether a particular triangulation object
-   * is able to distribute meshes between processes.
+   * A base class for distributed triangulations, i.e., triangulations that
+   * do not store all cells on all processors. This implies that not
+   * every detail of a triangulation may be known on each processor.
+   * In particular, you have to expect that triangulations of classes
+   * derived from this one only store some of the active cells (namely,
+   * the @ref GlossLocallyOwnedCell "locally owned cells"), along
+   * with @ref GlossGhostCell "ghost cells" and possibly
+   * @ref GlossArtificialCell "artificial cells". In contrast to the classes
+   * derived from parallel::TriangulationBase, it is certain that the
+   * classes derived from the current class will not store the entire
+   * triangulation as long as it has a large enough number of cells. (The
+   * difference to parallel::TriangulationBase is that the
+   * parallel::shared::Triangulation is derived from
+   * parallel::TriangulationBase, but not from the current class.) The
+   * distinction is not large in practice: Everything that is difficult for
+   * parallel distributed triangulation is generally also difficult for any
+   * other kind of parallel triangulation classes; however, this intermediate
+   * base class allows to further differentiate between the different kinds of
+   * classes providing parallel mesh functionality.
+   *
+   * This class can, then, be used to test whether a
+   * pointer or reference to a triangulation object refers to any kind of
+   * parallel triangulation, or whether the triangulation is in fact
+   * parallel distributed. In other words, one could write a function like
+   * this:
+   * @code
+   *   template <int dim, int spacedim>
+   *   bool
+   *   is_parallel_distributed(const dealii::Triangulation<dim,spacedim> &tria)
+   *   {
+   *     if(dynamic_cast<const
+   *                     parallel::DistributedTriangulationBase<dim,spacedim>*>
+   *                    (&tria)
+   *        != nullptr)
+   *       return true;
+   *     else
+   *       return false;
+   *   }
+   * @endcode
    */
   template <int dim, int spacedim = dim>
   class DistributedTriangulationBase