From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Mon, 18 Nov 2019 17:32:16 +0000 (-0700)
Subject: Clarify documentation.
X-Git-Tag: v9.2.0-rc1~870^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=942b43dcabc4335f48e3f820e4b68cd0ec465df2;p=dealii.git

Clarify documentation.
---

diff --git a/include/deal.II/fe/fe_values.h b/include/deal.II/fe/fe_values.h
index da9b132a57..2b0e292ced 100644
--- a/include/deal.II/fe/fe_values.h
+++ b/include/deal.II/fe/fe_values.h
@@ -3113,10 +3113,16 @@ public:
   get_inverse_jacobians() const;
 
   /**
-   * For a face, return the outward normal vector to the cell at the
-   * <tt>i</tt>th quadrature point.
-   *
-   * For a cell of codimension one, return the normal vector. There are of
+   * Return the normal vector at a quadrature point. If you call this
+   * function for a face (i.e., when using a FEFaceValues or FESubfaceValues
+   * object), then this function returns the outward normal vector to
+   * the cell at the <tt>i</tt>th quadrature point of the face.
+   *
+   * In contrast, if you call this function for a cell of codimension one
+   * (i.e., when using a `FEValues<dim,spacedim>` object with
+   * `spacedim>dim`), then this function returns the normal vector to the
+   * cell -- in other words, an approximation to the normal vector to the
+   * manifold in which the triangulation is embedded. There are of
    * course two normal directions to a manifold in that case, and this
    * function returns the "up" direction as induced by the numbering of the
    * vertices.
@@ -3129,9 +3135,9 @@ public:
   normal_vector(const unsigned int i) const;
 
   /**
-   * Return the normal vectors at the quadrature points. For a face, these are
-   * the outward normal vectors to the cell. For a cell of codimension one,
-   * the orientation is given by the numbering of vertices.
+   * Return the normal vectors at all quadrature points represented by
+   * this object. See the normal_vector() function for what the normal
+   * vectors represent.
    *
    * @dealiiRequiresUpdateFlags{update_normal_vectors}
    *
@@ -3143,9 +3149,9 @@ public:
   get_all_normal_vectors() const;
 
   /**
-   * Return the normal vectors at the quadrature points. For a face, these are
-   * the outward normal vectors to the cell. For a cell of codimension one,
-   * the orientation is given by the numbering of vertices.
+   * Return the normal vectors at all quadrature points represented by
+   * this object. See the normal_vector() function for what the normal
+   * vectors represent.
    *
    * @dealiiRequiresUpdateFlags{update_normal_vectors}
    */