From 1be1a109b437abff0078d9281b697e94b4f491df Mon Sep 17 00:00:00 2001
From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Wed, 21 Aug 2019 12:49:41 -0600
Subject: [PATCH] Update documentation of FE_PolyTensor.

---
 .../deal.II/base/tensor_polynomials_base.h    |  5 +--
 include/deal.II/fe/fe_poly.h                  |  6 ++--
 include/deal.II/fe/fe_poly_tensor.h           | 32 ++++++++-----------
 3 files changed, 21 insertions(+), 22 deletions(-)

diff --git a/include/deal.II/base/tensor_polynomials_base.h b/include/deal.II/base/tensor_polynomials_base.h
index cbd82f3767..e672f71cdf 100644
--- a/include/deal.II/base/tensor_polynomials_base.h
+++ b/include/deal.II/base/tensor_polynomials_base.h
@@ -30,8 +30,9 @@ DEAL_II_NAMESPACE_OPEN
 /**
  * This class provides a framework for the finite element polynomial
  * classes for use with finite element classes that are derived from
- * @p FE_Poly and @p FE_PolyTensor. An object of this type is stored
- * as a member variable in the finite element class.
+ * FE_PolyTensor. An object of this type (or rather of a type derived
+ * from this class) is stored as a member variable each object of
+ * type FE_PolyTensor.
  *
  * <h3>Deriving classes</h3>
  *
diff --git a/include/deal.II/fe/fe_poly.h b/include/deal.II/fe/fe_poly.h
index 1f299f03fa..57a4419522 100644
--- a/include/deal.II/fe/fe_poly.h
+++ b/include/deal.II/fe/fe_poly.h
@@ -29,8 +29,10 @@ DEAL_II_NAMESPACE_OPEN
 
 /**
  * This class gives a unified framework for the implementation of
- * FiniteElement classes based on polynomial spaces like the
- * TensorProductPolynomials or PolynomialSpace classes.
+ * FiniteElement classes based on scalar polynomial spaces like the
+ * TensorProductPolynomials or PolynomialSpace classes. This
+ * class has a corresponding class for tensor-valued finite
+ * elements in the FE_PolyTensor class.
  *
  * Every class that has the following public member variables and
  * functions can be used as template parameter @p PolynomialType.
diff --git a/include/deal.II/fe/fe_poly_tensor.h b/include/deal.II/fe/fe_poly_tensor.h
index 1fa69c4156..4b71a96b4b 100644
--- a/include/deal.II/fe/fe_poly_tensor.h
+++ b/include/deal.II/fe/fe_poly_tensor.h
@@ -33,24 +33,17 @@
 DEAL_II_NAMESPACE_OPEN
 
 /**
- * This class gives a unified framework for the implementation of
- * FiniteElement classes based on Tensor valued polynomial spaces like
- * PolynomialsBDM and PolynomialsRaviartThomas.
+ * This class provides a unified framework for the implementation of
+ * FiniteElement classes based on tensor-valued polynomial spaces like
+ * PolynomialsBDM and PolynomialsRaviartThomas. In this, it is the
+ * tensor-valued equivalent of the FE_Poly class.
  *
  * In essence, what this class requires is that a derived class describes
  * to it a (vector-valued) polynomial space in which every polynomial
- * has exactly @p dim vector components. The polynomial space is described
- * through the @p PolynomialType template argument, which needs to provide
- * a function of the following signature:
- * @code
- * void compute (const Point<dim>            &unit_point,
- *               std::vector<Tensor<1,dim> > &values,
- *               std::vector<Tensor<2,dim> > &grads,
- *               std::vector<Tensor<3,dim> > &grad_grads) const;
- * @endcode
- *
- * For more information on the template parameter <tt>spacedim</tt>, see the
- * documentation for the class Triangulation.
+ * has exactly @p dim vector components. The classes that provide such
+ * implementations are all derived from the TensorPolynomialsBase
+ * class, and an object of one of these derived types needs to be
+ * provided to the constructor of this class.
  *
  *
  * <h3>Deriving classes</h3>
@@ -58,13 +51,16 @@ DEAL_II_NAMESPACE_OPEN
  * This class is not a fully implemented FiniteElement class, but implements
  * some common features of vector valued elements based on vector valued
  * polynomial classes. What's missing here in particular is information on the
- * topological location of the node values, and derived classes need to provide
+ * topological location of the node values (i.e., whether a degree of freedom
+ * is logically at a vertex, edge, face, or the interior of a cell --
+ * information that determines the continuity properties of the associated
+ * shape functions across cell interfaces), and derived classes need to provide
  * this information.
  *
  * Similarly, in many cases, node functionals depend on the shape of the mesh
  * cell, since they evaluate normal or tangential components on the faces. In
  * order to allow for a set of transformations, the variable #mapping_kind has
- * been introduced. It should needs be set in the constructor of a derived
+ * been introduced. It needs be set in the constructor of a derived
  * class.
  *
  * Any derived class must decide on the polynomial space to use.  This
@@ -138,7 +134,7 @@ DEAL_II_NAMESPACE_OPEN
  * mappings, then @p mapping_kind may be a vector with the same number
  * of elements as there are shape functions.
  *
- * @see PolynomialsBDM, PolynomialsRaviartThomas
+ * @see TensorPolynomialsBase
  * @ingroup febase
  * @author Guido Kanschat
  * @date 2005
-- 
2.39.5