Utils/Logger: Reorganize source code

[senf.git] / Utils / Logger / Config.hh

diff --git a/Utils/Logger/Config.hh b/Utils/Logger/Config.hh
index 0cc8362..a9bf7c7 100644 (file)
--- a/Utils/Logger/Config.hh
+++ b/Utils/Logger/Config.hh
@@ -33,9 +33,87 @@
 #include "Config.ih"
 ///////////////////////////////hh.p////////////////////////////////////////
 
+/** \defgroup config Configuration
+
+    The logger infrastructure provides for very fine-grained configuration of log messages. There
+    are two parts to this configuration: compile-time configuration and runtime configuration.
+
+    <em>Compile-time</em> configuration selects, which log statements will even be compiled. If
+    logging for a certain combination of stream, area and level is disabled at compile time, no code
+    will be generated for any such disabled log statement. This type of configuration is done using
+    \ref SENF_LOG_CONF.
+
+    <em>Runtime</em> configuration on the other hand deals with routing all those messages, which
+    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.
+ */
+
 namespace senf {
 namespace log {
 
+    ///\ingroup config
+    ///\{
+
+#   ifdef DOXYGEN
+
+    /** \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)
+
+        The formal syntax of this option is:
+
+        \par ""
+            <table class="ebnf">
+            <tr><td>conf</td>         <td>::= \e element \e element* \n</td></tr>
+            <tr><td>element</td>      <td>::= <tt>((</tt> \e stream <tt>,</tt> \e optional_area <tt>,</tt> \e level <tt>))</tt> \n</td></tr>
+            <tr><td>stream</td>       <td>::= \e scope_seq \n</td></tr>
+            <tr><td>optional_area</td><td>::= <tt>(_)</tt> | \e scope_seq \n</td></tr>
+            <tr><td>level</td>        <td>::= \c VERBOSE | \c NOTICE | \c MESSAGE | \c IMPORTANT | \c CRITICAL | \c DISABLED \n</td></tr>
+            <tr><td>scope_seq</td>    <td>::= \e scope \e scope \e scope* \n</td></tr>
+            <tr><td>scope</td>        <td>::= <tt>(</tt> \e name <tt>)</tt> \n</td></tr>
+            <tr><td>name</td>         <td>::= arbitrary C++ identifier</td></tr>
+            </table>
+
+        \ref SENF_LOG_CONF is a Boost.Preprocessor style sequence of 3-tuples. Each tuple applies to
+        a specific stream which is defined by the first tuple element \e stream. 
+
+        The next tuple element, \e optional_area optionally restricts the entry to match only the
+        given area. 
+
+        The last tuple element \e level defines the compile time log level. Messages with a level
+        below this are discarded at compile time.
+
+        Both \e stream and \e optional_area are given as a \e scope_seq. A scope sequence is a fully
+        qualified C++ identifier placed into a sequence: <tt>foo::bar::baz</tt> is represented by
+        <tt>(foo)(bar)(baz)</tt>.
+     */
+#   define SENF_LOG_CONF
+
+#   endif
+
+    /** \brief Check, if logging is enabled for stream/area/level tuple
+        
+        This is a template meta-function which will check, whether logging to the given combination
+        of parameters \a Stream, \a Area and \a Level is compile-time enabled. The logging might
+        still be disabled at runtime.
+        \code
+        if (senf::log::Enabled<senf::log::Debug, 
+                               senf::log::DefaultArea, 
+                               senf::log::VERBOSE>::value) {
+            // ...
+        }
+        \endcode
+
+        Since the \e value member is a compile time constant, the compiler will completely optimize
+        away this block of code when logging is disabled.
+     */
     template <class Stream, class Area, class Level>
     struct Enabled
     {
@@ -44,6 +122,8 @@ namespace log {
                 >= detail::Config<Stream,Area>::compileLimit::value );
     };
 
+    ///\}
+
 }}
 
 ///////////////////////////////hh.e////////////////////////////////////////