Update the documentation of FECollection::find_last...().

diff --git a/include/deal.II/hp/fe_collection.h b/include/deal.II/hp/fe_collection.h
index f43dcda4b10ef6cf1ba10d0ef34382e9035b93af..15a41dde80e679197f5326cf54f265f6cc60eb79 100644 (file)
--- a/include/deal.II/hp/fe_collection.h
+++ b/include/deal.II/hp/fe_collection.h
@@ -246,12 +246,27 @@ namespace hp
     /**
      * Try to find a least dominant finite element inside this FECollection
      * which dominates all of those finite elements in the current collection
-     * indexed by the numbers provided through @p fes . For example, if
+     * indexed by the numbers provided through @p fes . In other words, we
+     * first form the set of elements in this collection that dominate
+     * all of the ones that are indexed by the argument @p fes, and then
+     * within that set of dominating elements, we find the <i>least</i>
+     * dominant one.
+     *
+     * For example, if
      * an FECollection consists of `{FE_Q(1),FE_Q(2),FE_Q(3),FE_Q(4)}` elements
-     * and we are looking for the least dominant finite element among the
-     * last two elements of this collection (i.e., @p fes is `{2,3}`), then
-     * the answer is FE_Q(3) and therefore this function will return its index
-     * in the FECollection, namely `2`.
+     * and the argument @p fes equals `{2,3}`, then the set of dominating
+     * elements consists of `{0,1,2}`, of which `2` (i.e., the `FE_Q(3)`) is the
+     * least dominant one, and then that's what the function returns.
+     *
+     * On the other hand, if the
+     * FECollection consists of
+     * `{FE_Q(1)xFE_Q(1),FE_Q(2)xFE_Q(2),FE_Q(2)xFE_Q(3), FE_Q(3)xFE_Q(2)}`
+     * elements and the argument is again
+     * @p fes equal to `{2,3}`, then the set of dominating
+     * elements consists of `{0,1}` because now neither of the last two
+     * elements dominates the other, of which `1` (i.e., the `FE_Q(2)xFE_Q(2)`)
+     * is the least dominant one -- so that's what the function returns in
+     * this case.
      *
      * For the purpose of this function by domination we consider either
      * FiniteElementDomination::Domination::this_element_dominates or
@@ -260,16 +275,18 @@ namespace hp
      * contains `{FE_Q(1),FE_Q(2),FE_Q(3),FE_Q(4)}` and @p fes only has
      * a single element `{3}`, then the function returns 3.
      *
-     * If the function is not able to find a finite element, the function
-     * returns numbers::invalid_unsigned_int .
-     *
-     * Note that for the cases like when FECollection consists of `{FE_Nothing
+     * If the function is not able to find a finite element that satisfies
+     * the description above, the function
+     * returns numbers::invalid_unsigned_int . An example would go like this:
+     * If the FECollection consists of `{FE_Nothing
      * x FE_Nothing, FE_Q(1)xFE_Q(2), FE_Q(2)xFE_Q(1)}` with @p fes as `{1}`,
      * the function will not find a most dominating element as the default
      * behavior of FE_Nothing is to return
      * FiniteElementDomination::no_requirements when comparing for face
-     * domination with any other element. This, therefore, can't be considered
-     * as a dominating element in the sense described above.
+     * domination with any other element. In other words, the set of
+     * dominating elements is empty, and we can not find a least dominant
+     * one among it. The return value is therefore
+     * numbers::invalid_unsigned_int.
      */
     unsigned int
     find_least_face_dominating_fe(const std::set<unsigned int> &fes) const;