improve documentation and arg naming of cell neighbor*()

My students rightfully got confused about the documentation and the
confusing argument name i. Try to fix things.

diff --git a/include/deal.II/grid/tria_accessor.h b/include/deal.II/grid/tria_accessor.h
index 9022adfade2625fa95942012858b03c8f16d5347..f54176e70f611b2de4b592c1c95989faf77c21da 100644 (file)
--- a/include/deal.II/grid/tria_accessor.h
+++ b/include/deal.II/grid/tria_accessor.h
@@ -2924,10 +2924,13 @@ public:
                             const unsigned int subface_no) const;
 
   /**
-   * Return a pointer to the @p ith neighbor.  If the neighbor does not exist,
+   * Return an iterator to the neighboring cell on the other side of the face
+   * with number @p face_no. If the neighbor does not exist,
    * i.e., if the @p ith face of the current object is at the boundary, then
    * an invalid iterator is returned.
    *
+   * Consequently, the index @p face_no must be less than n_faces().
+   *
    * The neighbor of a cell has at most the same level as this cell. For
    * example, consider the following situation:
    * @image html limit_level_difference_at_vertices.png ""
@@ -2940,40 +2943,46 @@ public:
    *
    * On the other hand, if you were at the top right cell of the four small
    * cells at the top left, and you asked for the right neighbor (which is
-   * associated with index <code>i=1</code>), then you would get the large
+   * associated with index <code>face_no=1</code>), then you would get the large
    * cell at the top right which in this case has a lower refinement level and
    * no children of its own.
    */
   TriaIterator<CellAccessor<dim, spacedim>>
-  neighbor(const unsigned int i) const;
+  neighbor(const unsigned int face_no) const;
 
   /**
-   * Return the index of the @p ith neighbor.  If the neighbor does not exist,
-   * its index is -1.
+   * Return the cell index of the neighboring cell on the other side of the face
+   * with index @p face_no. If the neighbor does not exist, this function returns -1.
+   *
+   * This function is equivalent to <tt>cell->neighbor(face_no)->index()</tt>.
+   * See neighbor() for more details.
    */
   int
-  neighbor_index(const unsigned int i) const;
+  neighbor_index(const unsigned int face_no) const;
 
   /**
-   * Return the level of the @p ith neighbor.  If the neighbor does not exist,
-   * its level is -1.
+   * Return the level of the neighboring cell on the other side of the face with
+   * number @p face_no. If the neighbor does not exist, this function returns -1.
+   *
+   * This function is equivalent to <tt>cell->neighbor(face_no)->level()</tt>.
+   * See neighbor() for more details.
    */
   int
-  neighbor_level(const unsigned int i) const;
+  neighbor_level(const unsigned int face_no) const;
 
   /**
    * Return the how-many'th neighbor this cell is of
-   * <tt>cell->neighbor(neighbor)</tt>, i.e. return the @p face_no such that
-   * <tt>cell->neighbor(neighbor)->neighbor(face_no)==cell</tt>. This function
-   * is the right one if you want to know how to get back from a neighbor to
-   * the present cell.
+   * <tt>cell->neighbor(face_no)</tt>, i.e. return the @p other_face_no such that
+   * <tt>cell->neighbor(face_no)->neighbor(other_face_no)==cell</tt>. This
+   * function is the right one if you want to know how to get back from a
+   * neighbor to the present cell.
    *
    * Note that this operation is only useful if the neighbor is not coarser
    * than the present cell. If the neighbor is coarser this function throws an
    * exception. Use the @p neighbor_of_coarser_neighbor function in that case.
    */
   unsigned int
-  neighbor_of_neighbor(const unsigned int neighbor) const;
+  neighbor_of_neighbor(const unsigned int face_no) const;
 
   /**
    * Return, whether the neighbor is coarser then the present cell. This is
@@ -2986,7 +2995,7 @@ public:
    * the finer face is either a child or a grandchild of the coarser face.
    */
   bool
-  neighbor_is_coarser(const unsigned int neighbor) const;
+  neighbor_is_coarser(const unsigned int face_no) const;
 
   /**
    * This function is a generalization of the @p neighbor_of_neighbor function

diff --git a/include/deal.II/grid/tria_accessor.templates.h b/include/deal.II/grid/tria_accessor.templates.h
index a9b3b15cb9be4cd8d9e595b2ee3a8356874644a0..e38575a64a80a031a4f6387c1917806e5aba13bd 100644 (file)
--- a/include/deal.II/grid/tria_accessor.templates.h
+++ b/include/deal.II/grid/tria_accessor.templates.h
@@ -3230,11 +3230,12 @@ CellAccessor<dim, spacedim>::face_index(const unsigned int i) const
 
 template <int dim, int spacedim>
 inline int
-CellAccessor<dim, spacedim>::neighbor_index(const unsigned int i) const
+CellAccessor<dim, spacedim>::neighbor_index(const unsigned int face_no) const
 {
-  AssertIndexRange(i, this->n_faces());
+  AssertIndexRange(face_no, this->n_faces());
   return this->tria->levels[this->present_level]
-    ->neighbors[this->present_index * GeometryInfo<dim>::faces_per_cell + i]
+    ->neighbors[this->present_index * GeometryInfo<dim>::faces_per_cell +
+                face_no]
     .second;
 }
 
@@ -3242,11 +3243,12 @@ CellAccessor<dim, spacedim>::neighbor_index(const unsigned int i) const
 
 template <int dim, int spacedim>
 inline int
-CellAccessor<dim, spacedim>::neighbor_level(const unsigned int i) const
+CellAccessor<dim, spacedim>::neighbor_level(const unsigned int face_no) const
 {
-  AssertIndexRange(i, this->n_faces());
+  AssertIndexRange(face_no, this->n_faces());
   return this->tria->levels[this->present_level]
-    ->neighbors[this->present_index * GeometryInfo<dim>::faces_per_cell + i]
+    ->neighbors[this->present_index * GeometryInfo<dim>::faces_per_cell +
+                face_no]
     .first;
 }
 
@@ -3521,11 +3523,11 @@ CellAccessor<dim, spacedim>::clear_coarsen_flag() const
 
 template <int dim, int spacedim>
 inline TriaIterator<CellAccessor<dim, spacedim>>
-CellAccessor<dim, spacedim>::neighbor(const unsigned int i) const
+CellAccessor<dim, spacedim>::neighbor(const unsigned int face_no) const
 {
   TriaIterator<CellAccessor<dim, spacedim>> q(this->tria,
-                                              neighbor_level(i),
-                                              neighbor_index(i));
+                                              neighbor_level(face_no),
+                                              neighbor_index(face_no));
 
   Assert((q.state() == IteratorState::past_the_end) || q->used(),
          ExcInternalError());

diff --git a/source/grid/tria_accessor.cc b/source/grid/tria_accessor.cc
index d14bfcdb6e8882b99e8e3fb81ba7538efcea7e6b..0720118b286ff74482d369f4ab96ea5bc9178236 100644 (file)
--- a/source/grid/tria_accessor.cc
+++ b/source/grid/tria_accessor.cc
@@ -2360,9 +2360,9 @@ CellAccessor<dim, spacedim>::neighbor_of_neighbor_internal(
 template <int dim, int spacedim>
 unsigned int
 CellAccessor<dim, spacedim>::neighbor_of_neighbor(
-  const unsigned int neighbor) const
+  const unsigned int face_no) const
 {
-  const unsigned int n2 = neighbor_of_neighbor_internal(neighbor);
+  const unsigned int n2 = neighbor_of_neighbor_internal(face_no);
   Assert(n2 != numbers::invalid_unsigned_int,
          TriaAccessorExceptions::ExcNeighborIsCoarser());
 
@@ -2374,9 +2374,9 @@ CellAccessor<dim, spacedim>::neighbor_of_neighbor(
 template <int dim, int spacedim>
 bool
 CellAccessor<dim, spacedim>::neighbor_is_coarser(
-  const unsigned int neighbor) const
+  const unsigned int face_no) const
 {
-  return neighbor_of_neighbor_internal(neighbor) ==
+  return neighbor_of_neighbor_internal(face_no) ==
          numbers::invalid_unsigned_int;
 }