Improve documentation. In particular, the description of the 'INITTree'

file format does not belong in the class description, because the class
parses other input sources as well.

[[Imported from SVN: r6514]]

dune/common/parametertreeparser.hh

@@ -10,60 +10,63 @@
 
 namespace Dune {
 
-  /** \brief Parser for hierarchical configuration files
+  /** \brief Parsers to set up a ParameterTree from various input sources
    * \ingroup Common
    *
-   * This class parses config files into a hierarchical structure.
-   * Config files should look like this
-   *
-     \verbatim
-   # this file configures fruit colors in fruitsalad
+   */
+  class ParameterTreeParser
+  {
 
+    static std::string ltrim(const std::string& s);
+    static std::string rtrim(const std::string& s);
 
-   ##these are no fruit but could also appear in fruit salad
-     honeydewmelon = yellow
-     watermelon = green
 
-     fruit.tropicalfruit.orange = orange
+  public:
 
-     [fruit]
-     strawberry = red
-     pomegranate = red
+    /** @name Parsing methods for the INITTree file format
+     *
+     *  INITTree files should look like this
+     *  \verbatim
+     # this file configures fruit colors in fruitsalad
 
-     [fruit.pipfruit]
-     apple = green/red/yellow
-     pear = green
 
-     [fruit.stonefruit]
-     cherry = red
-     plum = purple
+     ##these are no fruit but could also appear in fruit salad
+       honeydewmelon = yellow
+       watermelon = green
 
-     \endverbatim
-   *
-   *
-   * If a '[prefix]' statement appears all following entries use this prefix
-   * until the next '[prefix]' statement. Fruitsalads for example contain:
-     \verbatim
-     honeydewmelon = yellow
-     fruit.tropicalfruit.orange = orange
-     fruit.pipfruit.apple = green/red/yellow
-     fruit.stonefruit.cherry = red
-     \endverbatim
-   *
-   * All keys with a common 'prefix.' belong to the same substructure called
-   * 'prefix'.  Leading and trailing spaces and tabs are removed from the
-   * values unless you use single or double quotes around them.  Using single
-   * or double quotes you can also have multiline values.
-   *
-   */
-  class ParameterTreeParser
-  {
+       fruit.tropicalfruit.orange = orange
 
-    static std::string ltrim(const std::string& s);
-    static std::string rtrim(const std::string& s);
+       [fruit]
+       strawberry = red
+       pomegranate = red
 
+       [fruit.pipfruit]
+       apple = green/red/yellow
+       pear = green
+
+       [fruit.stonefruit]
+       cherry = red
+       plum = purple
+
+       \endverbatim
+     *
+     *
+     * If a '[prefix]' statement appears all following entries use this prefix
+     * until the next '[prefix]' statement. Fruitsalads for example contain:
+       \verbatim
+       honeydewmelon = yellow
+       fruit.tropicalfruit.orange = orange
+       fruit.pipfruit.apple = green/red/yellow
+       fruit.stonefruit.cherry = red
+       \endverbatim
+     *
+     * All keys with a common 'prefix.' belong to the same substructure called
+     * 'prefix'.  Leading and trailing spaces and tabs are removed from the
+     * values unless you use single or double quotes around them.  Using single
+     * or double quotes you can also have multiline values.
+     */
+    //@{
 
-  public:
     /** \brief parse C++ stream
      *
      * Parses C++ stream and build hierarchical config structure.
@@ -108,6 +111,7 @@ namespace Dune {
      */
     static void readINITree(std::string file, ParameterTree& pt, bool overwrite = true);
 
+    //@}
 
     /** \brief parse command line
      *