From: Wolfgang Bangerth Date: Wed, 2 Sep 2020 22:47:16 +0000 (-0600) Subject: Improve documentation of a rather basic function. X-Git-Tag: v9.3.0-rc1~1141^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f8f3ab0a19227b4a2d7149a7ad7658960df051a1;p=dealii.git Improve documentation of a rather basic function. --- diff --git a/include/deal.II/grid/tria.h b/include/deal.II/grid/tria.h index 83ac285f8b..3803f31a7c 100644 --- a/include/deal.II/grid/tria.h +++ b/include/deal.II/grid/tria.h @@ -1868,17 +1868,25 @@ public: set_all_refine_flags(); /** - * Refine all cells @p times times, by alternatingly calling - * set_all_refine_flags and execute_coarsening_and_refinement. - * - * The latter function may throw an exception if it creates cells that are - * distorted (see its documentation for an explanation). This exception will - * be propagated through this function if that happens, and you may not get - * the actual number of refinement steps in that case. + * Refine all cells @p times times. In other words, in each one of + * the @p times iterations, loop over all cells and refine each cell + * uniformly into $2^\text{dim}$ children. In practice, this + * function repeats the following operations @p times times: call + * set_all_refine_flags() followed by + * execute_coarsening_and_refinement(). The end result is that the + * number of cells increases by a factor of + * $(2^\text{dim})^\text{times}=2^{\text{dim} \times \text{times}}$. + * + * The execute_coarsening_and_refinement() function called in this + * loop may throw an exception if it creates cells that are + * distorted (see its documentation for an explanation). This + * exception will be propagated through this function if that + * happens, and you may not get the actual number of refinement + * steps in that case. * * @note This function triggers the pre- and post-refinement signals before * and after doing each individual refinement cycle (i.e. more than once if - * times > 1) . See the section on signals in the general documentation of + * `times > 1`) . See the section on signals in the general documentation of * this class. */ void