From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Sat, 6 Oct 2018 00:07:37 +0000 (-0600)
Subject: Update the documentation of FECollection::find_last...().
X-Git-Tag: v9.1.0-rc1~656^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=311f88c92e9e0575a6f431e8412440d8696736a9;p=dealii.git

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 f43dcda4b1..15a41dde80 100644
--- 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;