From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Tue, 16 Nov 2021 01:17:30 +0000 (-0700)
Subject: Minor updates to the documentation of CellData.
X-Git-Tag: v9.4.0-rc1~829^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F12951%2Fhead;p=dealii.git

Minor updates to the documentation of CellData.
---

diff --git a/include/deal.II/grid/tria_description.h b/include/deal.II/grid/tria_description.h
index ac9dfea989..b2c26cf4c3 100644
--- a/include/deal.II/grid/tria_description.h
+++ b/include/deal.II/grid/tria_description.h
@@ -21,6 +21,7 @@
 #include <deal.II/base/mpi.h>
 
 #include <deal.II/grid/cell_id.h>
+#include <deal.II/grid/reference_cell.h>
 #include <deal.II/grid/tria.h>
 
 #include <deal.II/lac/la_parallel_vector.h>
@@ -72,6 +73,20 @@ struct CellData
    * Indices of the vertices of this cell. These indices correspond
    * to entries in the vector of vertex locations passed to
    * Triangulation::create_triangulation().
+   *
+   * By default, the constructor of this class initializes this variable to
+   * have as many entries as it takes to describe a hypercube cell (i.e., a
+   * ReferenceCells::Line, ReferenceCells::Quadrilateral, or
+   * ReferenceCells::Hexahedron). This is historical and dates back to the time
+   * where deal.II could only deal with these kinds of cells. If you want an
+   * object of the current type to describe, for example, a triangle or
+   * tetrahedron, then you either have to call this constructor with an explicit
+   * argument different from the default value, or manually resize the
+   * `vertices` member variable after construction.
+   *
+   * The kind of cell described by the current object is then determined by
+   * calling ReferenceCell::n_vertices_to_type() on the number of vertices
+   * described by this array.
    */
   std::vector<unsigned int> vertices;
 
@@ -121,10 +136,20 @@ struct CellData
    *
    * - vertex indices to invalid values
    * - boundary or material id zero (the default for boundary or material ids)
-   * - manifold id to numbers::flat_manifold_id
+   * - manifold id to numbers::flat_manifold_id.
+   *
+   * By default, the constructor initializes the `vertices` member variable to
+   * have as many entries as it takes to describe a hypercube cell (i.e., a
+   * ReferenceCells::Line, ReferenceCells::Quadrilateral, or
+   * ReferenceCells::Hexahedron). This is historical and dates back to the time
+   * where deal.II could only deal with these kinds of cells. If you want an
+   * object of the current type to describe, for example, a triangle or
+   * tetrahedron, then you either have to call this constructor with an explicit
+   * argument different from the default value, or manually resize the
+   * `vertices` member variable after construction.
    */
-  CellData(
-    const unsigned int n_vertices = GeometryInfo<structdim>::vertices_per_cell);
+  CellData(const unsigned int n_vertices =
+             ReferenceCells::get_hypercube<structdim>().n_vertices());
 
   /**
    * Comparison operator.
@@ -205,9 +230,10 @@ struct SubCellData
 {
   /**
    * A vector of CellData<1> objects that describe boundary and manifold
-   * information for edges of 2d or 3d triangulations.
+   * information for edges of 2d or 3d triangulations. For 2d triangulations,
+   * edges (lines) are of course the faces of the cells.
    *
-   * This vector may not be used in the creation of 1d triangulations.
+   * This vector must not be used in the creation of 1d triangulations.
    */
   std::vector<CellData<1>> boundary_lines;
 
@@ -219,7 +245,11 @@ struct SubCellData
    * necessarily quadrilaterals. However, the variable is now also used to
    * describe boundary triangles for tetrahedral and mixed meshes.
    *
-   * This vector may not be used in the creation of 1d or 2d triangulations.
+   * Whether an element in this array describes a boundary triangle or a
+   * boundary quad is determined by how many elements the `vertices`
+   * member variable of `CellData<2>` stores.
+   *
+   * This vector must not be used in the creation of 1d or 2d triangulations.
    */
   std::vector<CellData<2>> boundary_quads;