From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Mon, 16 Aug 2021 23:53:09 +0000 (-0600)
Subject: Update documentation of FE_Q constructor.
X-Git-Tag: v9.4.0-rc1~1068^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=23df68064dd73f4151f6059af3890e58014ce562;p=dealii.git

Update documentation of FE_Q constructor.
---

diff --git a/include/deal.II/fe/fe_q.h b/include/deal.II/fe/fe_q.h
index b77dcef2f6..f451b7df8d 100644
--- a/include/deal.II/fe/fe_q.h
+++ b/include/deal.II/fe/fe_q.h
@@ -559,11 +559,16 @@ public:
    * Constructor for tensor product polynomials with support points @p points
    * based on a one-dimensional quadrature formula. The degree of the finite
    * element is <tt>points.size()-1</tt>. Note that the first point has to be
-   * 0 and the last one 1. Constructing
+   * 0 and the last one 1, to ensure that the resulting element is continuous.
+   * As a consequence, only *certain* quadrature formulas make sense as
+   * argument to this constructor. Specifically, constructing
    * <tt>FE_Q<dim>(QGaussLobatto<1>(fe_degree+1))</tt> is equivalent to the
    * constructor that specifies the polynomial degree only. For selecting
-   * equidistant nodes at <tt>fe_degree > 2</tt>, construct
-   * <tt>FE_Q<dim>(QIterated<1>(QTrapezoid<1>(),fe_degree))</tt>.
+   * equidistant nodes at <tt>fe_degree > 2</tt>, use
+   * <tt>FE_Q<dim>(QIterated<1>(QTrapezoid<1>(),fe_degree))</tt>, though the
+   * use of equidistant node points is known to lead to poorly conditioned
+   * linear systems with poor interpolation properties for high polynomial
+   * degrees (which is why the default uses the QGaussLobatto points).
    *
    * The *space* created by this constructor is the
    * same as if you had called `FE_Q<dim>(points.size()-1)`, but what *is*