From: g0dil <g0dil@270642c3-0616-0410-b53a-bc976706d245>
Date: Mon, 16 Nov 2009 11:01:43 +0000 (+0000)
Subject: Utils/Console: Special utility type documentation
X-Git-Url: http://g0dil.de/git?p=senf.git;a=commitdiff_plain;h=f7f08ce8a2ffd9a8004ab04a22a8ed434c0812f7

Utils/Console: Special utility type documentation

git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@1528 270642c3-0616-0410-b53a-bc976706d245
---

diff --git a/senf/Utils/Console/Mainpage.dox b/senf/Utils/Console/Mainpage.dox
index e5f90e4..51b6360 100644
--- a/senf/Utils/Console/Mainpage.dox
+++ b/senf/Utils/Console/Mainpage.dox
@@ -1176,9 +1176,9 @@
     After this setup, \c varChanged will be called, whenever the value has changed.
 
 
-    \section console_args Special argument types
+    \section console_args Special types
 
-    By default, argument types which can be read and written using \c iostreams are automatically
+    By default, types which can be read and written using \c iostreams are automatically
     supported. Other types need to be registered explicitly
 
 
@@ -1271,7 +1271,7 @@
     \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
@@ -1291,7 +1291,14 @@
     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.
 
-    The same idea can be used to support custom parsing rules. See senf::console::FlagCollection.
+    
+    \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).
+
+    \see \ref senf_console_utilities
 
 
     \subsection console_args_custom Extending the library to support additional types
diff --git a/senf/Utils/Console/Utility.hh b/senf/Utils/Console/Utility.hh
index 5c2b263..79f95d4 100644
--- a/senf/Utils/Console/Utility.hh
+++ b/senf/Utils/Console/Utility.hh
@@ -33,9 +33,34 @@
 //#include "Utility.mpp"
 ///////////////////////////////hh.p////////////////////////////////////////
 
+/** \defgroup senf_console_utilities Special console utility types
+
+    These types are provided by the %console library to support special argument or return value
+    formatting rules.
+ */
+
 namespace senf {
 namespace console {
 
+    /** \brief Parse character value as single-char string
+
+        This helper types is a wrapper around \a CharT which must be a character type. A value of
+        this type will be represented as a single character string, not as numeric value (the
+        default interpretation of char arguments in the console library).
+
+        This wrapper is used via type conversion using \c boost::function to convert the
+        argument/return type \a CharT  to CharAsString<CharT>:
+        \code
+        char foo(char v) { return v; }
+        
+        senf::console::root().add(
+            "foo", boost::function< CharAsString<char> (CharAsString<char>) >(&foo));
+        \endcode
+
+        \tparam CharT character type, one of \c char, \c signed \c char or \c unsigned \c char
+
+        \ingroup senf_console_utilities
+     */
     template <class CharT>
     struct CharAsString
     {
@@ -71,7 +96,9 @@ namespace console {
     /** \brief Value range
         
         A value range may be represented in the console either by a single value (setting both \a
-        low and \a high to the same value) or as a lower and upper bound seperated by a colon
+        low and \a high to the same value) or as a lower and upper bound seperated by a colon.
+
+        \ingroup senf_console_utilities
      */
     template <class T>
     struct ValueRange
@@ -142,6 +169,8 @@ namespace console {
         console:/$ func Foo
         console:/$ func (Foo Boo)
         </pre>
+
+        \ingroup senf_console_utilities
      */
     template <class Enum>
     struct FlagCollection
diff --git a/tools/find-doxy-source.sh b/tools/find-doxy-source.sh
new file mode 100755
index 0000000..1d3d2e4
--- /dev/null
+++ b/tools/find-doxy-source.sh
@@ -0,0 +1,14 @@
+#!/bin/sh -e
+
+base="`dirname "$0"`"
+
+text="`echo "$1" | perl -pe 's/[^a-zA-Z0-9]+/ /g;s/^ //;s/ $//'`"
+${base}/find-sources.sh -c \
+    | xargs perl -0777ne '
+          while(m{/\*\*<?(.*?)\*/|///<?(.*?)$}smg) {
+              $t=$1||$2;
+              $t=~s/\\\S+//g;
+              $t=~s/[^a-zA-Z0-9]+/ /g;
+              print $ARGV,"\n" if $t=~m{\Q'"$text"'\E};
+          }'\
+    | sort -u