Add doxygen docs for new grid creation process

* Add module for grid creation
* Add author and date information
* Improve docstrings of classes and functions

dune/dorie/common/grid_creator.hh

@@ -37,6 +37,9 @@ namespace Dorie {
  *  soil layers (parameter sets) via the GridMapper.
  *
  *  \tparam Grid The type of the grid to build
+ *  \ingroup Grid
+ *  \author Lukas Riedel
+ *  \date 2018
  */
 template<typename Grid>
 class GridCreator

dune/dorie/common/modules.dox

@@ -35,6 +35,75 @@
     Notice that `helper` will be of *reference* type `Dune::MPIHelper &`.
 @}
 
+@defgroup Grid Grid Creation and Mapping Utilities
+@{
+  @ingroup Common
+  @brief Classes for building grids and load-balancing mapping data
+
+  ## Overview
+
+  DORiE offers a variety of grid setups which require different DUNE grid
+  managers and different setup routines. For structured rectangular grids,
+  we use `Dune::YaspGrid`, and for unstructured rectangular or simplex grids,
+  we use `Dune::UGGrid`.
+
+  In addition to the actual grid, DORiE also manages mappings of grid elements
+  (cells) and boundary segments to indices. These indices are used to refer to
+  medium layers in case of cells and boundary conditions in case of boundary
+  faces. Through the medium layer, a certain
+  \ref RichardsParam "hydraulic Parameterization" is applied to the
+  respective cell.
+
+  The Dorie::GridCreator builds a DUNE grid from the settings given in the
+  config file. It then internally assembles the Dorie::GridMapper which
+  loads the mapping data and load-balances it appropriately across all
+  processes if executed in parallel. The resulting local maps are retrieved
+  by the Dorie::GridCreator and can be queried by the user.
+  
+  There are two general ways of constructing a grid:
+
+  1. Assembling an unstructured grid from a [GMSH](http://gmsh.info/)
+     file. This always uses `UGGrid`. GMSH has the capability of storing
+     grid element and boundary mappings and the `Dune::GmshReader` also loads
+     this information. It is then passed to the `GridMapper` and properly
+     load-balanced, as the `GmshReader` currently only works sequentially.
+  
+  2. Building a rectangular grid with user-defined extensions and numbers
+     of cells in each direction. Depending on wether grid adaptivity was
+     enabled, this either creates a `UGGrid` or a `YaspGrid`. In both cases,
+     the user has to supply the mapping information separately. DORiE offers
+     two options here: Mapping a single ("global") index to all elements,
+     or reading a mapping dataset. This H5 dataset must have the same shape
+     as the grid. Each of its values maps to a single grid cell.
+
+  ## Constructing The Grid
+
+  Initialize the grid creator with the config file settings. This will
+  automatically build the grid.
+
+  @code{.cc}
+    Dune::Dorie::GridCreator<GridType> grid_creator(config, helper);
+  @endcode
+  
+  Retrieve a shared pointer to the grid from it. The grid will already be
+  properly load-balanced.
+
+  @code{.cc}
+    auto grid = grid_creator.grid();
+  @endcode
+  
+  The index maps are managed by the `GridMapper`, which is created internally.
+  After initializing the `GridCreator`, they can be retrieved from it.
+  Notice that these maps only remain valid if the grid is **not load-balanced
+  any further** (e.g., after local grid refinement)!
+
+  @code{.cc}
+    auto element_index_map = grid_creator.get_element_index_map();
+    auto boundary_index_map = grid_creator.get_boundary_index_map();
+  @endcode
+
+@}
+
 @defgroup Logging Terminal Logging
 @{
   @ingroup Common