Utils/Logger: Documentation

Utils/Logger/AreaRegistry.hh

@@ -43,11 +43,13 @@ namespace log {
 
     /** \brief Area registry 
         
-        The area registry keeps track of all areas defined. Area classes are defined as singletons
-        and will automatically register with this registry.
+        The area registry keeps track of all areas defined. 
 
-        The area registry exposes a forward sequence interface which is a sequence of the names of
-        all registered areas.
+        The area registry exposes a forward sequence interface which allows to query the list of all
+        registered areas.
+
+        \implementation Area classes are defined as singletons and will automatically register with
+        this registry.
      */
     class AreaRegistry
         : public senf::singleton<AreaRegistry>
@@ -62,6 +64,7 @@ namespace log {
 
     public:
         typedef boost::transform_iterator<SelectName, Registry::const_iterator> iterator;
+                                        ///< Iterator type
 
 #       ifdef DOXYGEN
         // Hmm ... doxygen does not understand using declarations ...
@@ -71,8 +74,8 @@ namespace log {
 
         using senf::singleton<AreaRegistry>::instance;
 
-        iterator begin();
-        iterator end();
+        iterator begin();               ///< Beginning of area name sequence
+        iterator end();                 ///< End of area name sequence
 
     private:
         AreaRegistry();

Utils/Logger/Config.hh

@@ -47,6 +47,47 @@
     are enabled at compile time to the logging targets. If a message is not routed, it will be
     discarded. This allows to additionally disable messages at run-time. Message routing is managed
     via the \ref Target interface.
+
+    \section config_compile Compile time configuration
+
+    Compile time configuration is set on the compiler command line:
+    <pre>
+    g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Debug),(_),DISABLED ))
+                             (( (senf)(log)(Debug),(foo)(SomeClass),VERBOSE ))
+                             (( (foo)(Transactions),(_),NOTICE ))" ...
+    </pre>
+    The value is relatively complex; It's a Boost.Preprocessor style sequence of tuples, of which
+    the first and second elements are again sequences. What this boils down to, is that it allows to
+    configure compile time logging limits based on stream and optional area. 
+
+    The above example disables all debug logging by setting the default log limit for all areas on
+    the \c senf::log::Debug stream to \c DISABLED. It then re-enables debug logging only within the
+    \c foo::SomeClass area, where it is set to \c VERBOSE. Furthermore, the limit on the \c
+    foo::Transactions stream is set to \c NOTICE.
+
+    \section config_runtime Runtime configuration
+
+    The runtime configuration is performed by routing messages to one or more logging targets:
+    \code
+    senf::log::ConsoleLog consoleLog;
+    senf::log::FileLog fileLog ("my.log");
+
+    consoleLog.route<senf::log::Debug>();
+    consoleLog.route<foo::Transactions, foo::SomeClass>(senf::log::Target::REJECT);
+    consoleLog.route<foo::Transactions, senf::log::IMPORTANT>();
+
+    fileLog.route<foo::Transactions>();
+    \endcode Here we see an already relatively complex setup: All debug messages (that is, those,
+    which are not disabled at compile time) are routed to the console. We also route important
+    transactions to the console \e except transactions from the \c foo::SomeClass area. The \c
+    fileLog simply receives all transaction log messages.
+
+    The routing statements are processed by the targets in order, the first matching rule will
+    decide a log messages fate for that target.
+
+    \see 
+        \ref SENF_LOG_CONF: compile time configuration \n
+        \ref senf::log::Target: runtime configuration
  */
 
 namespace senf {
@@ -60,13 +101,7 @@ namespace log {
     /** \brief Compile time configuration
 
         This define symbol sets the compile time logger configuration. This symbol should normally
-        be set on the compiler command line:
-        <pre>
-        g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Debug),(_),DISABLED ))
-                                 (( (senf)(log)(Debug),(foo)(SomeClass),VERBOSE ))
-                                 (( (foo)(Transactions),(_),NOTICE ))" ...
-        </pre>
-        (As this option can get quite long, you might want to use the '-imacros' option instead)
+        be set on the compiler command line.
 
         The formal syntax of this option is:
 

Utils/Logger/IOStreamTarget.hh

@@ -56,9 +56,6 @@ namespace log {
         
         \note This class will permanently and globally change the date formating of the given
             stream.
-
-        \fixme Implement more robust formatting: Find line-breaks in the message and repeat the
-            prefix (with continuation markers)
       */
     class IOStreamTarget
         : public Target

Utils/Logger/Log.hh

@@ -49,15 +49,16 @@
     SENF_LOG( (senf::log::Debug)(senf::log::NOTICE)(FroblizerArea)("The log message") );
     \endcode
 
-    For each log message, the following information is needed:
+    The argument is comprised of a sequence of parameters and the log message itself. The parameters
+    are
     \li The <em>log stream</em>,
     \li the <em>log area</em>,
     \li the <em>log level</em>,
-    \li and the log message itself
     
-    These parameters may be specified <i>in arbitrary order</i> and even multiple times in the
-    parameter sequence. If some argument type occurs multiple times, the last occurrence wins. If
-    any one of the parameters is not specified, it's current default value will be used.
+    These parameters are optional and may be specified <i>in arbitrary order</i> (with the log
+    message always being the last sequence element) and even multiple times in the parameter
+    sequence. If some argument type occurs multiple times, the last occurrence wins. If any one of
+    the parameters is not specified, it's current default value will be used.
 
     This current default value is set using \ref SENF_LOG_DEFAULT_STREAM, \ref SENF_LOG_DEFAULT_AREA
     and \ref SENF_LOG_DEFAULT_LEVEL respectively. These macros set the default stream, area and/or

Utils/Logger/Mainpage.dox

@@ -32,7 +32,31 @@
     \see
         \ref logging \n
         \ref config \n
+        \ref targets \n
+        \ref loglevels
 
+    \section logging_concepts Concepts
+
+    The log messages are devided along several categories: \e streams, \e areas and log \e levels.
+
+    A \e stream combines log messages with a single purpose. There is one default stream, called \c
+    senf::log::Debug. New streams are defined with \ref SENF_LOG_DEF_STREAM.
+
+    An \e area labels a log message with the source location of the message. An area is an arbitrary
+    tag which may be added to the message. There is one default area called \c
+    senf::log::DefaultArea. New areas are defined either with \ref SENF_LOG_DEF_AREA or \ref
+    SENF_LOG_CLASS_AREA, the latter being the more typical. The area will normally indicate the
+    class or subsystem from which the message was generated.
+
+    The log \e level gives information on the importance of the message. The list lof \ref loglevels
+    is fixed.
+
+    After log messages have been created, they have to be placed somewhere. This is the
+    responsibility of the \e target. A target is an arbitrary sink for log messages. The target
+    manages message routing and will pass the message on to it's destination, be it the system
+    console, some log file or some other place (e.g. an SQL database). The target is responsible for
+    formating the message.
+    
     \section logging_tutorial Tutorial introduction
 
     Using the logging library mostly concerns using \ref SENF_LOG statements in your code. There are