Utils/Console: Documentation fixes

[senf.git] / senf / Utils / Console / Mainpage.dox

diff --git a/senf/Utils/Console/Mainpage.dox b/senf/Utils/Console/Mainpage.dox
index e5f90e4..1811aa2 100644 (file)
--- a/senf/Utils/Console/Mainpage.dox
+++ b/senf/Utils/Console/Mainpage.dox
@@ -1176,11 +1176,64 @@
     After this setup, \c varChanged will be called, whenever the value has changed.
 
 
-    \section console_args Special argument types
+    \section console_args Console library supported types
 
-    By default, argument types which can be read and written using \c iostreams are automatically
-    supported. Other types need to be registered explicitly
+    By default, types which can be read and written using \c iostreams are automatically supported. 
+    This includes all the C++ built-in types as well as user defined streamable types.
 
+    An exception is made for all \c char types: These types are by default parsed as \e numeric
+    values not single-character data. To interpret \c char values as single-char strings, use \ref
+    senf::console::CharAsString.
+
+    \subsection console_args_stl STL container support
+
+    The %console library contains support for the STL container types: \c std::vector, \c
+    std::list, \c std::set, \c std::multiset, \c std::map and \c std::multimap.
+
+    All container types are parsed as parenthesized list of elements. Each element is parsed as
+    defined for the element type:
+
+    \c vector, \c list or \c set of integers:
+    <pre>
+    (1 2 3)
+    </pre>
+
+    \c vector, \c list or \c set of strings:
+    <pre>
+    ("String 1" "String 2" "String 3")
+    </pre>
+
+    \c vector, \c list or \c set of <tt>pair<int,string></tt>:
+    <pre>
+    ((1 "String 1") (2 "String 2") (3 "String 3"))
+    </pre>
+
+    Empty collection:
+    <pre>
+    ()
+    </pre>
+    
+    Collection's with only one element may skip the parenthesis <em>if and only if</em> the element
+    type does not need additional parenthesis
+
+    A \c vector, \c list or \c set of integer with one element may be written with or without
+    parenthesis:
+    <pre>
+    (1) 
+    1
+    </pre>
+
+    \e but a single element \c vector, \c list or \c set of <tt>pair<int,string></tt> may \e only be
+    written:
+    <pre>
+    ((1 "String 1"))
+    </pre>
+
+    In mapping containers, the key and value are separated by \c =:
+    <pre>
+    (foo=1 bar=2 "foo bar"=3)
+    </pre>
+    
 
     \subsection console_args_bool Boolean arguments and return values
 
@@ -1271,27 +1324,34 @@
     \endhtmlonly
 
 
-    \subsection console_args_convert Handling special argument types by conversion
+    \subsection console_args_convert Handling argument types by conversion
 
     Sometimes an argument type is best handled by just pretending it to be of some other type. The
     basic idea is, to us \c boost::function to convert the real argument type to some different type
 
     \code
-    unsigned char fun4(unsigned char value)
+    int fun4(int value)
     {
         return value;
     }
     
     senf::console::root()
-        .add("test8", boost::function<unsigned (unsigned)>(&fun4));
+        .add("test8", boost::function<bool (bool)>(&fun4));
     \endcode
     
     Here, the type signature specified via \c boost::function is different from the real type
     signature but is compatible. \c boost::function automatically handles the conversion
-    process. Since the console library now sees the argument and return value of type \c unsigned,
-    the values will be parsed correctly as numeric values.
+    process. Since the console library now sees the argument and return value of type \c bool,
+    the values will be parsed and formatted as boolean values.
+
+    
+    \subsection console_args_special Special Console types
+
+    The %console library defines some special types to be used as arguments and/or return values.
+    Some of these are wrappers around basic types which provide custom formatting. Those are used
+    via argument type conversion (see previous section).
 
-    The same idea can be used to support custom parsing rules. See senf::console::FlagCollection.
+    \see \ref senf_console_utilities
 
 
     \subsection console_args_custom Extending the library to support additional types