X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Utils%2FLogger%2FLog.hh;h=8a591dc273bb685329ea64d9facb2bc97d3e3450;hb=fe593b5092295224c1f4334bcc97801d2cf41b89;hp=81b7703b5130ee5d2353e0e20b461ae424da51dd;hpb=61419d9a2e1060f7ede22fa19fd9d0b401bbc87a;p=senf.git

diff --git a/Utils/Logger/Log.hh b/Utils/Logger/Log.hh
index 81b7703..8a591dc 100644
--- a/Utils/Logger/Log.hh
+++ b/Utils/Logger/Log.hh
@@ -1,8 +1,8 @@
 // $Id$
 //
-// Copyright (C) 2007 
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
+// Copyright (C) 2007
+// Fraunhofer Institute for Open Communication Systems (FOKUS)
+// Competence Center NETwork research (NET), St. Augustin, GERMANY
 //     Stefan Bund <g0dil@berlios.de>
 //
 // This program is free software; you can redistribute it and/or modify
@@ -39,7 +39,7 @@
 
 /** \defgroup logging Logging commands
 
-    The logging library provides several commands to create log messages. All these macro commands
+    The logging library provides several commands to create %log messages. All these macro commands
     take a variable number of arguments. Since this is not supported in a usable way by the C++
     preprocessor, the arguments are encoded into a <a
     href="http://www.boost.org/libs/preprocessor/doc/index.html">Boost.Preprocessor</a> like
@@ -49,31 +49,50 @@
     SENF_LOG( (senf::log::Debug)(senf::log::NOTICE)(FroblizerArea)("The log message") );
     \endcode
 
-    For each log message, the following information is needed:
-    \li The <em>log stream</em>,
-    \li the <em>log area</em>,
-    \li the <em>log level</em>,
-    \li and the log message itself
+    The argument is comprised of a sequence of parameters and the %log message itself. 
+    The parameters are
+    - the <em>%log stream</em>,
+    - the <em>%log area</em>,
+    - the <em>%log level</em>.
     
-    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
-    level of the current scope. The logging library defines the global defaults for these values to
-    be \c senf::log::Debug (\e stream), senf::log::DefaultArea (\e area), and senf::log::NONE (\e
-    level).
+    level <em>of the current scope</em>. They may be used with a class declaration to set defaults
+    for all class members or within a function or member body to set the default for that member
+    only. They may be used only \e once within each scope.
 
-    There is one special log level, senf::log::NONE. If the log level is set to this value, the log
-    level will be set from the stream provided default value.
-    
+    The logging library defines the global defaults for stream, area and level to be \c
+    senf::log::Debug, senf::log::DefaultArea, and senf::log::NONE respectively.
 
+    The %log level senf::log::NONE is special. If the %log level is set to this value, the %log level
+    will be set from the stream provided default value.
+    
     All these parameters must be <em>compile time constants</em> (they are all types, so it's
-    difficult form them to be something else).
+    difficult for them to be something else).
+
+    \section logging_aliases Aliases
+
+    To further simplify logging commands, aliases may be defined within any scope. An alias is an
+    arbitrary collection of %log parameters:
+    \code
+    SENF_LOG_DEF_ALIAS( VerboseDebug, (senf::log::Debug)(senf::log::VERBOSE) );
+    \endcode
+    Within %log statements, aliases may be used like normal parameters. They will be substituted for
+    the parameter sequence they represent:
+    \code
+    SENF_LOG( (VerboseDebug)("Debug message") )
+    // is equivalent to
+    SENF_LOG( (senf::log::Debug)(senf::log::VERBOSE)("Debug message") )
+    \endcode
+    Aliases may be used together with other parameters, even with further aliases in any order.
  */
 
-///\ingroup logging
+///\addtogroup logging
 ///\{
 
 ///\name Generating log messages
@@ -128,8 +147,8 @@
     \hideinitializer
  */
 #define SENF_LOG_BLOCK_TPL(args)                                                                  \
-    SENF_LOG_BLOCK_( SENF_LOG_MERGE_PARAMETERS_TPL(BOOST_PP_SEQ_POP_BACK(args)),                  \
-                     BOOST_PP_SEQ_ELEM(BOOST_PP_DEC(BOOST_PP_SEQ_SIZE(args)),args))
+    SENF_LOG_BLOCK_TPL_( SENF_LOG_MERGE_PARAMETERS_TPL(BOOST_PP_SEQ_POP_BACK(args)),              \
+                         BOOST_PP_SEQ_ELEM(BOOST_PP_DEC(BOOST_PP_SEQ_SIZE(args)),args))
 
 ///\}
 ///\}