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 7cb989897832af1aa23620935bea10456df1bdf6..c2a2a563baab2d62639150471c8b24ae50c7d777 100644 (file)
--- 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 44b50b94c41dd63d6e3e8ad569b8aa47cb845100..5214e06cd8c59feee9ef572fb01cad297949ca32 100644 (file)
--- 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 25831589c2b1576f282a4714ccce2f2d42d7ed05..467241a4a39d423be24647b0ba17960c266c8635 100644 (file)
--- 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));
       }