Update docstrings of GridMapper

dune/dorie/solver/util_grid_mapper.hh

@@ -39,10 +39,14 @@ private:
     std::vector<int> _boundary_index_map;
 
 public:
-    /// Create the grid mapper from a *unbalanced* grid.
+    /// Create the grid mapper from a grid using global IDs.
     /** All data structures received must be located on a single process.
      *  After constructing this GridMapper, the grid and the maps are properly
      *  partitioned and can be retrieved using the getter functions.
+     *
+     *  Local maps are produced using global IDs.
+     *
+     *  \todo Handle boundary index map properly! (Feature pending)
      *  \param grid Shared pointer to the grid.
      *  \param element_index_map The element index map for the entire grid.
      *  \param boundary_index_map The boundary index map for the entire grid.
@@ -73,8 +77,15 @@ public:
         broadcast_vector(_boundary_index_map);
     }
 
-    /// Create a GridMapper for a rectangular grid.
-    /** \param grid Shared pointer to the grid
+    /// Create a GridMapper for a rectangular grid using cell coordinates.
+    /** This constructor immediately calls the default load-balance on the grid.
+     *  After constructing this GridMapper, the grid and the maps are properly
+     *  partitioned and can be retrieved using the getter functions.
+     *
+     *  Local maps are produced using the cell coordinates.
+     *
+     *  \todo Handle boundary index map properly! (Feature pending)
+     *  \param grid Shared pointer to the grid
      *  \param cells Number of cells in each direction
      *  \param element_index_map The element index map for the entire grid.
      *  \param boundary_index_map The boundary index map for the entire grid.
@@ -118,8 +129,12 @@ public:
     std::shared_ptr<Grid> get_grid () const { return _grid; }
 
 private:
-    /// Build a local element_index_map from the global one and cell numberings
-    /** \param cells Number of cells in each direction
+    /// Build a local element_index_map from the global one and cell indices.
+    /** This method assumes that the global index mapping is based on the
+     *  cells' positions on the grid and that indices follow the spatial
+     *  dimensions, where x runs faster than y and z.
+     *
+     *  \param cells Number of cells in each direction
      */
     void rebuild_index_maps (const std::vector<int>& cells)
     {
@@ -145,8 +160,11 @@ private:
         _element_index_map = new_element_index_map;
     }
 
-    /// Build a element_index_map from a id_map
-    /** \param id_map The ID map to build the index map from
+    /// Build a local element_index_map from a global ID mapping
+    /** The global ID is consistent across all processors and is used for
+     *  identifying the respective cell.
+     *
+     *  \param id_map The ID map to build the index map from
      */
     void rebuild_index_maps (const std::map<IdType, int>& id_map)
     {