From 9e0e79c55cee78622debef99e5f4eaa6992237d8 Mon Sep 17 00:00:00 2001
From: Ichthyostega <prg@ichthyostega.de>
Date: Sun, 30 Nov 2008 06:24:37 +0100
Subject: [PATCH] comments for logging config

---
 src/include/{nobugcfg.hpp => nobugcfg.h} | 39 ++++++++++++++++--------
 1 file changed, 27 insertions(+), 12 deletions(-)
 rename src/include/{nobugcfg.hpp => nobugcfg.h} (63%)

diff --git a/src/include/nobugcfg.hpp b/src/include/nobugcfg.h
similarity index 63%
rename from src/include/nobugcfg.hpp
rename to src/include/nobugcfg.h
index 9b37bbd11..70de908fb 100644
--- a/src/include/nobugcfg.hpp
+++ b/src/include/nobugcfg.h
@@ -1,5 +1,5 @@
 /*
-  NOBUGCFG.hpp  -  NoBug definitions and initialisation for the Proc-Layer
+  NOBUGCFG.h  -  NoBug definitions and initialisation for the Proc-Layer
  
  
   Copyright (C)         Lumiera.org
@@ -30,16 +30,31 @@
  ** this header will be included via some of the basic headers like error.hpp,
  ** which in turn gets included e.g. by proc/common.hpp
  **
- ** @par This header can thus be assumed to be effectively global. It should contain
+ ** This header can thus be assumed to be effectively global. It should contain
  ** only declarations of global relevance, as any change causes the whole project 
  ** to be rebuilt. Moreover, for C++ this header assures automatic initialisation
  ** of NoBug by placing a static ctor call.
  **
- ** @par Besides the usual guarded declarations, this header contains one section
+ ** Besides the usual guarded declarations, this header contains one section
  ** with the corresponding <b>definitions</b>. This section is to be included once
  ** by some translation unit (currently this is lumiera/nobugcfg.cpp) in order to
- ** generate the necessary definitions. 
- **
+ ** generate the necessary definitions.
+ ** 
+ ** @par Logging configuration
+ ** By default, logging is configured such as to emit a small number of informative
+ ** messages on the starting terminal and to report fatal errors. But besides the
+ ** usual fine-grained tracing messages, we define a small number of distinct 
+ ** thematic <b>Logging Channels</b> providing a consistent high-level view of
+ ** what is going on with regards to a specific aspect of the application
+ ** - \c operate documents a high-level overall view of what the application \em does
+ ** - \c render focuses on the working of the render engine (without logging each frame)
+ ** - \c config shows anything of relevance regarding the configured state of App and session
+ ** - \c memory allows to diagnose a high-level view of memory management
+ ** 
+ ** Any log level can be overridden by an environment variable, for example
+ ** \code NOBUG_LOG='operate:INFO' ./lumiera \endcode
+ ** 
+ ** @todo logging to files?
  */
 
 
@@ -52,7 +67,7 @@
 
 #ifdef __cplusplus  /* ============= C++ ================ */
 
-#include "lumiera/appconfig.hpp"
+#include "lumiera/appstate.hpp"
 #include "include/error.hpp"  ///< make assertions throw instead of abort()
 
 namespace lumiera { 
@@ -65,14 +80,14 @@ namespace lumiera {
 
 
 
-  /* declare flags used throughout the code base... */
+  /* declare flags used throughout the code base */
   NOBUG_DECLARE_FLAG (all);
   NOBUG_DECLARE_FLAG (lumiera_all);
-  NOBUG_DECLARE_FLAG (lumiera);
-  NOBUG_DECLARE_FLAG (operate);
-  NOBUG_DECLARE_FLAG (render);
-  NOBUG_DECLARE_FLAG (config);
-  NOBUG_DECLARE_FLAG (memory);
+  NOBUG_DECLARE_FLAG (lumiera);        ///< master log, informative console output
+  NOBUG_DECLARE_FLAG (operate);        ///< logging channel reporting what the application does
+  NOBUG_DECLARE_FLAG (render);         ///< logging channel focusing on the render engine's workings
+  NOBUG_DECLARE_FLAG (config);         ///< logging channel covering application and session configuration
+  NOBUG_DECLARE_FLAG (memory);         ///< logging channel covering memory management issues
   NOBUG_DECLARE_FLAG (test);