From: David Wells <drwells@email.unc.edu>
Date: Tue, 29 Jun 2021 14:23:23 +0000 (-0400)
Subject: Improve the documentation of TriaAccessor::is_ghost().
X-Git-Tag: v9.4.0-rc1~1183^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F12521%2Fhead;p=dealii.git

Improve the documentation of TriaAccessor::is_ghost().

The documentation isn't quite right for p::s::T. Now that we have three parallel
Triangulation classes we should be a bit more careful in describing some of
their distinctions.
---

diff --git a/include/deal.II/distributed/shared_tria.h b/include/deal.II/distributed/shared_tria.h
index d967fe7661..9b13f8e0c9 100644
--- a/include/deal.II/distributed/shared_tria.h
+++ b/include/deal.II/distributed/shared_tria.h
@@ -351,7 +351,7 @@ namespace parallel
       get_true_level_subdomain_ids_of_cells(const unsigned int level) const;
 
       /**
-       * Return allow_artificial_cells , namely true if artificial cells are
+       * Return allow_artificial_cells, namely true if artificial cells are
        * allowed.
        */
       bool
diff --git a/include/deal.II/grid/tria_accessor.h b/include/deal.II/grid/tria_accessor.h
index e2a2a1dd37..d0f3eb8793 100644
--- a/include/deal.II/grid/tria_accessor.h
+++ b/include/deal.II/grid/tria_accessor.h
@@ -3678,14 +3678,18 @@ public:
   is_locally_owned_on_level() const;
 
   /**
-   * Return whether this cell exists in the global mesh but (i) is owned by
-   * another processor, i.e. has a subdomain_id different from the one the
-   * current processor owns and (ii) is adjacent to a cell owned by the
-   * current processor.
-   *
-   * This function only makes sense if the triangulation used is of kind
-   * parallel::distributed::Triangulation. In all other cases, the returned
-   * value is always false.
+   * Return true if:
+   * <ol>
+   * <li>This cell exists in the global mesh (i.e., it is not artificial),
+   * and</li>
+   * <li>This cell is owned by another processor (i.e., has a subdomain_id
+   * different from Triangulation::locally_owned_subdomain())</li>
+   * </ol>
+   *
+   * In all other cases the returned value is false. In particular, only
+   * parallel Triangulations (i.e., Triangulations inheriting from
+   * parallel::TriangulationBase) can have ghost cells, so for a serial
+   * Triangulation the returned value is false.
    *
    * See the
    * @ref GlossGhostCell "glossary"
@@ -3696,7 +3700,13 @@ public:
    * @post The returned value is equal to <code>!is_locally_owned() &&
    * !is_artificial()</code>.
    *
-   * @note Whether a cell is a ghost cell, artificial, or is locally owned or
+   * @note For parallel::distributed::Triangulation and
+   * parallel::fullydistributed::Triangulation, ghost cells are always adjacent
+   * to locally owned cells. For parallel::shared::Triangulation they may not
+   * be, dependent on whether or not the triangulation uses artificial cells -
+   * see parallel::shared::Triangulation::Triangulation() for more information.
+   *
+   * @note Whether a cell is a ghost cell, artificial, or is locally owned
    * is a property that only pertains to cells that are active. Consequently,
    * you can only call this function if the cell it refers to has no children.
    */