X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Utils%2FLogger%2FMainpage.dox;h=d7a7e898ac224a105028a3fef95b6929342457ed;hb=c7512677a51c8ba551ab23611d6e99bdc7a7fdfa;hp=f30c1fb054568ecef8f30b1d9045c813fd434246;hpb=61419d9a2e1060f7ede22fa19fd9d0b401bbc87a;p=senf.git

diff --git a/Utils/Logger/Mainpage.dox b/Utils/Logger/Mainpage.dox
index f30c1fb..d7a7e89 100644
--- a/Utils/Logger/Mainpage.dox
+++ b/Utils/Logger/Mainpage.dox
@@ -32,7 +32,38 @@
     \see
         \ref logging \n
         \ref config \n
-
+        \ref targets \n
+        \ref loglevels
+
+    \section logging_concepts Concepts
+
+    Log messages are arbitrarily created throughout the code using simple log statements (which are
+    macros). Besides the log message itself, every log message is labeled with additional
+    information: The \e stream, the \e area and a log \e level. If the message is not compile-time
+    disabled, the message is then directed to one or several log \e targets.
+
+    A \e stream combines log messages with a single purpose: Debug messages, access logging and so
+    on. Any number of streams may be defined. There is one predefined default stream called \c
+    senf::log::Debug. (see: \ref SENF_LOG_DEF_STREAM)
+
+    The \e area gives information about the source location of the message. Areas may be defined and
+    assigned arbitrarily but should be used to label messages from a single class or subsystem. It
+    is possible to reuse a class as it's own area tag, which is often desireable.  There is a
+    default area \c senf::log::DefaultArea which is used, when no other area is assigned. (see: \ref
+    SENF_LOG_DEF_AREA, \ref SENF_LOG_CLASS_AREA)
+
+    The log \e level gives information on the importance of the message. The list of log-levels is
+    fixed. (see: \ref loglevels)
+
+    Depending on their the \e stream, \e area and \e level information, log messages can be enabled
+    or disabled at \e compile time. Messages disabled at compile time should not generate any
+    code. (see: \ref SENF_LOG_CONF)
+
+    To be of any use, the log messages have to be written somewhere. This is the responsibility of
+    any number of \e targets. A \e target receives messages and using it's routing information
+    decides, wether the message is output or not. A message may be routed to multiple targets
+    simultaneously or may not be output by any target at all. (see: \ref targets)
+    
     \section logging_tutorial Tutorial introduction
 
     Using the logging library mostly concerns using \ref SENF_LOG statements in your code. There are
@@ -43,7 +74,7 @@
 
         // Define a new log stream with default level, runtime limit and compile time limit 
         // set to senf::log::MESSAGE
-        SENF_LOG_DEF_STREAM( UserLog, senf::log::MESSAAGE, senf::log::MESSAGE, senf::log::MESSAGE );
+        SENF_LOG_DEF_STREAM( UserLog, senf::log::MESSAGE, senf::log::MESSAGE, senf::log::MESSAGE );
 
         class Froblizer
         {
@@ -51,8 +82,7 @@
             // This is a combination of SENF_LOG_DEF_AREA and SENF_LOG_DEFAULT_AREA.
             SENF_LOG_CLASS_AREA();
 
-            // Set default log parameters for this scope. The values here are not really
-            // necessary since these are the global default values
+            // Set default log parameters for this scope.
             SENF_LOG_DEFAULT_STREAM(foo::UserLog);
             SENF_LOG_DEFAULT_LEVEL(senf::log::NOTICE);
 
@@ -83,15 +113,29 @@
 
         SENF_LOG(("Log to UserLog stream in Froblizer area however at VERBOSE level"));
     }
+
+    int main(int, char **)
+    {
+        // Set up the routing targets
+        senf::log::ConsoleTarget console;
+        senf::log::FileTarget logfile ("my.log");
+
+        // Debug messages go to the console
+        console.route<senf::log::Debug>();
+        // Important user message are written to the log file
+        logfile.route<foo::UserLog, senf::log::IMPORTANT>();
+    }
     \endcode
 
     \implementation I would have much preferred a more C++ like implementation. However given the
         design goals
         \li Flexible configuration at compile and runtime
         \li Concise usage and simple interface
-        \li Zero overhead for compile-time disabled log messages I did not find any non-mcaro
-        implementation which was not either completely convoluted, unusable or slow. So I turned to
-        a macro based implementation which can provide all the design goals stated above.
+        \li Zero overhead for compile-time disabled log messages 
+
+        I did not find any non-mcaro implementation which was not either completely convoluted,
+        unusable or slow. So I turned to a macro based implementation which can provide all the
+        design goals stated above.
  */