Doc update in GridTools.

diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h
index c754900a93a1fe10af6cff179411dcb7a8aa5248..b04f3265c376804dcbfd68cbe3a20a539faee9d7 100644 (file)
--- a/include/deal.II/grid/grid_tools.h
+++ b/include/deal.II/grid/grid_tools.h
@@ -1896,7 +1896,13 @@ namespace GridTools
    * the given predicate is true, are completely enclosed in at least one of the
    * bounding boxes. Notice the cover is only guaranteed to contain all these
    * active cells but it's not necessarily exact i.e. it can include a bigger
-   * area than their union.
+   * area than their union. (This is of course unavoidable in any case if cells
+   * are not rectangular or brick-shaped, but it is also true if cells are
+   * since it is inefficient to create as many bounding boxes as there are
+   * cells; rather, the algorithm here tries to combine the bounding boxes
+   * of multiple cells into a cheaper representation, at the cost of a set
+   * of bounding boxes that may be larger than the union of the cells -- see
+   * the description of the relevant function arguments below.)
    *
    * For each cell at a given refinement level containing active cells for which @p predicate is true,
    * the function creates a bounding box of its children for which @p predicate is true.
@@ -1905,30 +1911,42 @@ namespace GridTools
    * @p allow_merge and @p max_boxes are used to reduce the number of cells at a computational cost and
    * covering a bigger n-dimensional volume.
    *
-   * The parameters to control the algorithm are:
-   * - @p predicate : the property of the cells to enclose e.g. IteratorFilters::LocallyOwnedCell .
-   *  The predicate is tested only on active cells.
-   * - @p refinement_level : it defines the level at which the initial bounding box are created. The refinement
-   *  should be set to a coarse refinement level. A bounding box is created for
-   * each active cell at coarser
-   *  level than @p refinement_level; if @p refinement_level is higher than the number of levels of the
+   * @param[in] mesh The mesh object this function is to work on. This
+   *   is generally either a triangulation of some kind, or a DoFHandler
+   *   object.
+   * @param[in] predicate A function-like object that returns true or
+   *   false depending on whether the property of the cells to enclose
+   *   is satisfied. An example is IteratorFilters::LocallyOwnedCell,
+   *   but it can also be a lambda function or anything else that can be
+   *   called with a cell as argument.
+   *   This predicate is tested only on active cells.
+   * @param[in] refinement_level Defines the level at which the
+   *  initial bounding boxes are created. The refinement should be set
+   *  to a coarse refinement level. A bounding box is created for each
+   *  active cell at a coarser level than @p refinement_level; if @p
+   *  refinement_level is higher than the number of levels of the
    *  triangulation an exception is thrown.
-   * - @p allow_merge : This flag allows for box merging and, by default, is false. The algorithm has a cost of
-   *  O(N^2) where N is the number of the bounding boxes created from the
-   * refinement level; for this reason, if
-   *  the flag is set to true, make sure to choose wisely a coarse enough @p refinement_level.
-   * - @p max_boxes : the maximum number of bounding boxes to compute. If more are created the smaller ones are
-   *  merged with neighbors. By default after merging the boxes which can be
-   * expressed as a single one no more boxes are merged. See the
-   * BoundingBox::get_neighbor_type () function for details.
-   *  Notice only neighboring cells are merged (see the @p get_neighbor_type  function in bounding box class): if
-   *  the target number of bounding boxes max_boxes can't be reached by merging
-   * neighbors an exception is thrown
-   *
-   * The following image describes an example of the algorithm with @p refinement_level = 2, @p allow_merge = true
-   * and @p max_boxes = 1. The cells with the property predicate are in red, the area of a bounding box is
-   * slightly orange.
+   * @param[in] allow_merge This flag allows for box merging and, by
+   *  default, is false. The algorithm has a cost of O(N^2) where N is
+   *  the number of the bounding boxes created from the refinement
+   *  level; for this reason, if the flag is set to true, make sure to
+   *  choose wisely a coarse enough @p refinement_level.
+   * @param[in] max_boxes The maximum number of bounding boxes to
+   *  compute. If more are created the smaller ones are merged with
+   *  neighbors. By default after merging the boxes which can be
+   *  expressed as a single one no more boxes are merged. See the
+   *  BoundingBox::get_neighbor_type () function for details.  Notice
+   *  only neighboring cells are merged (see the @p get_neighbor_type
+   *  function in bounding box class): if the target number of
+   *  bounding boxes max_boxes can't be reached by merging neighbors
+   *  an exception is thrown.
+   *
+   * The following image describes an example of the algorithm with @p
+   * refinement_level = 2, @p allow_merge = true and @p max_boxes =
+   * 1. The cells with the property predicate are in red, the area of
+   * a bounding box is slightly orange.
    * @image html bounding_box_predicate.png
+   *
    * - 1. In black we can see the cells of the current level.
    * - 2. For each cell containing the red area a bounding box is created: by
    * default these are returned.