Clarify why n_faces() is only possible on cells.

diff --git a/include/deal.II/grid/tria_accessor.h b/include/deal.II/grid/tria_accessor.h
index a8d0da59ddb782c3e1f76822548675f2127aedd2..7148294c372237e04a2398aa546721cc9b13dc32 100644 (file)
--- a/include/deal.II/grid/tria_accessor.h
+++ b/include/deal.II/grid/tria_accessor.h
@@ -1740,9 +1740,13 @@ public:
   n_lines() const;
 
   /**
-   * Number of faces.
-   *
-   * @note Only implemented for cells (structdim==dim).
+   * Return the number of faces for a cell. This function is only
+   * implemented for cells (i.e., `structdim==dim`) to avoid the question
+   * of what exactly is meant in a construct such as
+   * `cell->face(f)->n_faces()`. If you want to ask how many bounding
+   * lines a face of a 3d cell has, use `cell->face(f)->n_lines()`; if
+   * you want to ask about the number of vertices of a face of a 2d cell,
+   * use `cell->face(f)->n_vertices()`.
    */
   unsigned int
   n_faces() const;

diff --git a/include/deal.II/grid/tria_accessor.templates.h b/include/deal.II/grid/tria_accessor.templates.h
index e92a89927195d762c205da35df1b51cc2a255740..f9b70a7d76e3a08cee59a52240c6e6c1674cf2c9 100644 (file)
--- a/include/deal.II/grid/tria_accessor.templates.h
+++ b/include/deal.II/grid/tria_accessor.templates.h
@@ -2397,7 +2397,10 @@ template <int structdim, int dim, int spacedim>
 unsigned int
 TriaAccessor<structdim, dim, spacedim>::n_faces() const
 {
-  AssertDimension(structdim, dim);
+  Assert(structdim == dim,
+         ExcMessage("This function can only be used on objects "
+                    "that are cells, but not on faces or edges "
+                    "that bound cells."));
 
   return this->reference_cell().n_faces();
 }