From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Wed, 13 Sep 2017 13:44:13 +0000 (-0600)
Subject: Add to the documentation.
X-Git-Tag: v9.0.0-rc1~1091^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=74d278a79e40ee4ea60d57a9d9f4569c3f507043;p=dealii.git

Add to the documentation.
---

diff --git a/include/deal.II/dofs/dof_accessor.h b/include/deal.II/dofs/dof_accessor.h
index 104f07f85c..f647257a03 100644
--- a/include/deal.II/dofs/dof_accessor.h
+++ b/include/deal.II/dofs/dof_accessor.h
@@ -1694,6 +1694,15 @@ public:
    * indices on non-active cells since they do not have finite element spaces
    * associated with them without having any degrees of freedom. Consequently,
    * this function will produce an exception when called on non-active cells.
+   *
+   * @note When using parallel meshes, either through the
+   * parallel::shared::Triangulation or parallel::distributed::Triangulation
+   * classes, it is only allowed to call this function on locally
+   * owned or ghost cells. No information is available on artificial cells.
+   * Furthermore, @p active_fe_index information is exchanged from locally
+   * owned cells on one processor to other processors where they may be
+   * ghost cells, during the call to hp::DoFHandler::distribute_dofs().
+   * See the documentation of hp::DoFHandler for more information.
    */
   unsigned int active_fe_index () const;
 
@@ -1709,6 +1718,18 @@ public:
    * indices to non-active cells since they do not have finite element spaces
    * associated with them without having any degrees of freedom. Consequently,
    * this function will produce an exception when called on non-active cells.
+   *
+   * @note When using parallel meshes, either through the
+   * parallel::shared::Triangulation or parallel::distributed::Triangulation
+   * classes, it is only allowed to call this function on locally
+   * owned cells (see @ref GlossLocallyOwnedCell "this glossary entry"). This
+   * is because otherwise a common source of errors would be if one
+   * processor sets a different @p active_fe_index on a ghost cell than
+   * the processor that actually owns the cell does. To avoid this mistake,
+   * one can only set @p active_fe_index information on locally owned
+   * cells, and this information is then mirrored to all processors that
+   * have this cell as a ghost cell -- see the documentation of the
+   * hp::DoFHandler class.
    */
   void set_active_fe_index (const unsigned int i) const;
   /**