Update documentation about setting active FE indices.

diff --git a/include/deal.II/hp/dof_handler.h b/include/deal.II/hp/dof_handler.h
index c4be7e907a220793262d34c7456c1c41c618f150..4608bbaa85dae40bbd3e705cc7a656aa035a99b8 100644 (file)
--- a/include/deal.II/hp/dof_handler.h
+++ b/include/deal.II/hp/dof_handler.h
@@ -127,10 +127,30 @@ namespace hp
    *   are coarsened away, the old value is no longer available on the
    *   parent cell.
    *
+   *
+   * <h3>Active FE indices and parallel meshes</h3>
+   *
+   * When this class is used with either a parallel::shared::Triangulation
+   * or a parallel::distributed::Triangulation, you can only set active
+   * FE indices on cells that are locally owned or that are ghost cells,
+   * using a call such as <code>cell-@>set_active_fe_index(...)</code>.
+   * On the other hand, setting the active FE index on artificial cells
+   * is not allowed.
+   *
+   * However, setting the index on ghost cells has no real effect: whenever
+   * you call hp::DoFHandler::distribute_dofs(), all processors that
+   * participate in the parallel mesh exchange information in such a way
+   * that the active FE index on ghost cells equals the active FE index
+   * that was set on that processor that owned that particular ghost cell.
+   * In other words, information that may have previously been set on
+   * ghost cells is overwritten so that the active FE index there is
+   * consistent with the value on the processor that owns the cell.
+   *
+   *
    * @ingroup dofs
    * @ingroup hp
    *
-   * @author Wolfgang Bangerth, Oliver Kayser-Herold, 2003, 2004
+   * @author Wolfgang Bangerth, Oliver Kayser-Herold, 2003, 2004, 2017
    */
   template <int dim, int spacedim=dim>
   class DoFHandler : public Subscriptor