From 981b0ab6315829b991a60289c911fa81c40ab9e8 Mon Sep 17 00:00:00 2001 From: bangerth Date: Sun, 15 Jun 2014 15:45:45 +0000 Subject: [PATCH] Add some documentation and clarify an awkwardly explained concept. git-svn-id: https://svn.dealii.org/trunk@33046 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/include/deal.II/grid/tria.h | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/deal.II/include/deal.II/grid/tria.h b/deal.II/include/deal.II/grid/tria.h index 86d7789683..f60fd6e545 100644 --- a/deal.II/include/deal.II/grid/tria.h +++ b/deal.II/include/deal.II/grid/tria.h @@ -2879,14 +2879,22 @@ public: unsigned int n_active_faces () const; /** - * Return number of levels in use. This - * may be less than the number of levels - * existing in the triangulation if by - * coarsening the highest level was - * completely depopulated. That level is - * not removed, since it will most likely - * be repopulated soon by the next - * refinement process. + * Return the number of levels in this triangulation. + * + * @note Internally, triangulations store data in levels, and there + * may be more levels in this data structure than one may think -- + * for example, imagine a triangulation that we just got by + * coarsening the highest level so that it was completely + * depopulated. That level is not removed, since it will most likely + * be repopulated soon by the next refinement process. As a consequence, + * if you happened to run through raw cell iterators (which you can't + * do as a user of this class, but can internally), then the number + * of objects in the levels hierarchy is larger than the level of the most + * refined cell plus one. On the other hand, since this is rarely what a + * user of this class cares about, the function really just returns the + * level of the most refined active cell plus one. (The plus one is + * because in a coarse, unrefined mesh, all cells have level zero -- + * making the number of levels equal to one.) */ unsigned int n_levels () const; -- 2.39.5