[trac1024] Update documentation

src/lib/log/logger_support.h

@@ -19,10 +19,14 @@
 
 #include <string>
 #include <log/logger.h>
-
-// Include the unit test function declarations here for compatibility
 #include <log/logger_unittest_support.h>
 
+/// \file
+/// \brief Logging initialization functions
+///
+/// Contains a set of functions relating to logging initialization that are
+/// used by the production code.
+
 namespace isc {
 namespace log {
 
@@ -36,17 +40,13 @@ namespace log {
 /// \return true if logging has been initialized, false if not
 bool isLoggingInitialized();
 
-/// \brief Set "logging initialized" flag
-///
-/// Sets the state of the "logging initialized" flag.
+/// \brief Set state of "logging initialized" flag
 ///
 /// \param state State to set the flag to. (This is expected to be "true" - the
 ///        default - for all code apart from specific unit tests.)
 void setLoggingInitialized(bool state = true);
 
-
-
-/// \brief Run-Time Initialization
+/// \brief Run-time initialization
 ///
 /// Performs run-time initialization of the logger in particular supplying:
 ///
@@ -65,10 +65,7 @@ void initLogger(const std::string& root,
                 isc::log::Severity severity = isc::log::INFO,
                 int dbglevel = 0, const char* file = NULL);
 
-
-
 } // namespace log
 } // namespace isc
 
-
 #endif // __LOGGER_SUPPORT_H

src/lib/log/logger_unittest_support.h

@@ -18,7 +18,12 @@
 #include <string>
 #include <log/logger.h>
 
-// Note: this file holds logging functions used by unit tests.
+/// \file
+/// \brief Miscellaneous logging functions used by the unit tests.
+///
+/// As the configuration database is unsually unavailable during unit tests,
+/// the functions defined here allow a limited amount of logging configuration
+/// through the use of environment variables
 
 namespace isc {
 namespace log {
@@ -71,7 +76,7 @@ void initLogger(isc::log::Severity severity = isc::log::DEBUG,
                 int dbglevel = isc::log::MAX_DEBUG_LEVEL);
 
 
-/// \brief Logging Severity from B10_LOGGER_SEVERITY
+/// \brief Obtains logging severity from B10_LOGGER_SEVERITY
 ///
 /// Support function called by the unit test logging initialization code.
 /// It returns the logging severity defined by B10_LOGGER_SEVERITY.  If
@@ -84,7 +89,7 @@ void initLogger(isc::log::Severity severity = isc::log::DEBUG,
 isc::log::Severity b10LoggerSeverity(isc::log::Severity defseverity);
 
 
-/// \brief Logging Debug Level from B10_LOGGER_DBGLEVEL
+/// \brief Obtains logging debug level from B10_LOGGER_DBGLEVEL
 ///
 /// Support function called by the unit test logging initialization code.
 /// It returns the logging debug level defined by B10_LOGGER_DBGLEVEL.  If
@@ -103,7 +108,7 @@ isc::log::Severity b10LoggerSeverity(isc::log::Severity defseverity);
 int b10LoggerDbglevel(int defdbglevel);
 
 
-/// \brief Reset Root Logger Characteristics
+/// \brief Reset root logger characteristics
 ///
 /// This is a simplified interface into the resetting of the characteristics
 /// of the root logger.  It is aimed for use in unit tests and resets the

src/lib/python/isc/log/log.cc

@@ -269,10 +269,11 @@ PyMethodDef methods[] = {
         "'FATAL'), a debug level (integer in the range 0-99) and a file name "
         "of a dictionary with message text translations."},
     {"resetUnitTestRootLogger", resetUnitTestRootLogger, METH_VARARGS,
-        "Initialization for unit tests.  Sets the severity and output stream "
-        "according to a set of environment variables.  This should not be "
-        "used in production code.  The name is slightly confusing, but it "
-        "mirrors a method of the same name used for the C++ unit tests."},
+        "Resets the configuration of the root logger to that set by the "
+        "B10_XXX environment variables.  It is aimed at unit tests, where "
+        "the logging is initialized by the code under test; called before "
+        "the unit test starts, this function resets the logging configuration "
+        "to that in use for the C++ unit tests."},
     {"log_config_update", logConfigUpdate, METH_VARARGS,
         "Update logger settings. This method is automatically used when "
         "ModuleCCSession is initialized with handle_logging_config set "