Console: More simple argument parsing (argument iterator wrapper)

[senf.git] / Console / Example.dox

diff --git a/Console/Example.dox b/Console/Example.dox
index be71f69..c571c36 100644 (file)
--- a/Console/Example.dox
+++ b/Console/Example.dox
@@ -64,19 +64,67 @@
     main-loop after shutdownServer returns (which is ultimately called via the console server from
     the scheduler). Throwing a senf::console::Executor::ExitException is like entering the \c exit
     built-in command at the console.
+
+    The next callback accesses the client instance directly to manipulate the logging:
     
-    \until network
-    \until Example
+    \until }
+
+    The senf::console::Client instance can be accessed using the senf::console::Client::get() helper
+    via the output stream. Since every Client is a senf::log::Target, we can route arbitrary log
+    messages to the console instance.
+
+    We now define \c main() which initializes the node tree and starts the console server
+    
+    \until route
+    
+    Here we just setup more verbose logging and set \c SIGPIPE signals to be ignored. \c SIGPIPE's
+    are a pain and really should be disabled.
+    
+    \until settings
 
-    The \c main routine enables more verbose console logging and adds some directories and callbacks
-    to the tree so we have some stuff to play around with.
+    This shows, how to set the top-level documentation and create a new subdirectory.
 
-    The following few lines of code instantiate a \c TestObject instance and add this object's
-    directory node to the tree
+    \until doc
 
+    Here we create another new directory and save a reference so we can later access the node
+    directly. All the add commands return such a node reference of the correct type (this is a lie,
+    but it works like this anyways and it's an implementation detail that must not concern you
+    here).
+    
+    Instead of creating a new directory directly and later sotring a reference, it is better to use
+    \c senf::console::ScopedDirectory<> like this:
+
+    \until functions
+    
+    This will automatically remove the node from the tree when the \c senf::console::ScopedDirectory
+    instance is destroyed. It also protects against the problem of dangling references: When using a
+    plain reference, removing the directory from the tree will destroy the node. The reference
+    however will still reference the (now nonexistent) directory and any access via the reference
+    will crash the program. 
+
+    The next statements add commands to the various directories declared so far
+    
     \until Example
+
+    We now continue by creating an instance of our test class \c TestObject
     
-    Now we are ready to start the server and enter the Scheduler main-loop
+    \until Example
+
+    We add that objects directory to the \c test dir. We now have created a directory structure like
+    tis:
+    <pre>
+    /
+      console/
+        showlog
+      server/
+        shutdown
+      test/
+        echo
+        testob/
+          vat
+    </pre>
+
+    We now start the server (giving it a nice descriptive name) and run the scheduler.
 
     \until }
  */