From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Sat, 27 Feb 2021 00:39:32 +0000 (-0700)
Subject: Better document (and name) a ReferenceCell function.
X-Git-Tag: v9.3.0-rc1~392^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=68309e980e36a7bba29f1883000ab7a2c1089fde;p=dealii.git

Better document (and name) a ReferenceCell function.
---

diff --git a/include/deal.II/grid/reference_cell.h b/include/deal.II/grid/reference_cell.h
index 7cb9898978..c2a2a563ba 100644
--- a/include/deal.II/grid/reference_cell.h
+++ b/include/deal.II/grid/reference_cell.h
@@ -380,10 +380,17 @@ public:
                              const unsigned char face_orientation) const;
 
   /**
-   * Combine face and line orientation.
+   * Return whether the line with index @p line is oriented in
+   * standard direction within a cell, given the @p face_orientation of
+   * the face within the current cell, and @p line_orientation flag
+   * for the line within that face. @p true indicates that the line is
+   * oriented from vertex 0 to vertex 1, whereas it is the other way
+   * around otherwise. In 1d and 2d, this is always @p true, but in 3d
+   * it may be different, see the respective discussion in the
+   * documentation of the GeometryInfo class.
    */
   bool
-  combine_face_and_line_orientation(const unsigned int  line,
+  standard_vs_true_line_orientation(const unsigned int  line,
                                     const unsigned char face_orientation,
                                     const unsigned char line_orientation) const;
 
@@ -1729,7 +1736,7 @@ ReferenceCell::unit_normal_vectors(const unsigned int face_no) const
 
 
 inline bool
-ReferenceCell::combine_face_and_line_orientation(
+ReferenceCell::standard_vs_true_line_orientation(
   const unsigned int  line,
   const unsigned char face_orientation_raw,
   const unsigned char line_orientation) const
diff --git a/include/deal.II/grid/tria_accessor.h b/include/deal.II/grid/tria_accessor.h
index 44b50b94c4..5214e06cd8 100644
--- a/include/deal.II/grid/tria_accessor.h
+++ b/include/deal.II/grid/tria_accessor.h
@@ -924,6 +924,8 @@ public:
    *
    * This function is really only for internal use in the library unless you
    * absolutely know what this is all about.
+   *
+   * This function queries ReferenceCell::standard_vs_true_line_orientation().
    */
   bool
   line_orientation(const unsigned int line) const;
diff --git a/include/deal.II/grid/tria_accessor.templates.h b/include/deal.II/grid/tria_accessor.templates.h
index 25831589c2..467241a4a3 100644
--- a/include/deal.II/grid/tria_accessor.templates.h
+++ b/include/deal.II/grid/tria_accessor.templates.h
@@ -832,17 +832,20 @@ namespace internal
         Assert(accessor.used(), TriaAccessorExceptions::ExcCellNotUsed());
         AssertIndexRange(line, accessor.n_lines());
 
+        // First pick a face on which this line is a part of, and the
+        // index of the line within.
         const auto pair =
           accessor.reference_cell().standard_line_to_face_and_line_index(line);
         const auto quad_index = pair[0];
-        const auto line_index =
+        const auto line_within_face_index =
           accessor.reference_cell().standard_to_real_face_line(
             pair[1], pair[0], face_orientation_raw(accessor, quad_index));
 
-        return accessor.reference_cell().combine_face_and_line_orientation(
+        // Then query how that line is oriented within that face:
+        return accessor.reference_cell().standard_vs_true_line_orientation(
           pair[1],
           face_orientation_raw(accessor, quad_index),
-          accessor.quad(quad_index)->line_orientation(line_index));
+          accessor.quad(quad_index)->line_orientation(line_within_face_index));
       }