[trac555] Clarify comments

src/lib/log/logger_manager.cc

@@ -80,8 +80,8 @@ LoggerManager::init(const std::string& root, const char* file,
     // All other loggers created in this application will be its children.
     setRootLoggerName(root);
 
-    // Initialize the implementation logging.  After this point, some basic logging
-    // has been set up and messages can be logged.
+    // Initialize the implementation logging.  After this point, some basic
+    // logging has been set up and messages can be logged.
     LoggerManagerImpl::init(severity, dbglevel);
 
     // Check if there were any duplicate message IDs in the default dictionary
@@ -89,13 +89,13 @@ LoggerManager::init(const std::string& root, const char* file,
     vector<string>& duplicates = MessageInitializer::getDuplicates();
     if (!duplicates.empty()) {
 
-        // There are duplicates present.  This will be listed in alphabetic order of
-        // message ID, so they need to be sorted.  This list itself may contain
-        // duplicates; if so, the message ID is listed as many times as there are
-        // duplicates.
+        // There are duplicates present.  This will be listed in alphabetic
+        // order of message ID, so they need to be sorted.  This list itself may
+        // contain duplicates; if so, the message ID is listed as many times as
+        // there are duplicates.
         sort(duplicates.begin(), duplicates.end());
-        for (vector<string>::iterator i = duplicates.begin(); i != duplicates.end();
-             ++i) {
+        for (vector<string>::iterator i = duplicates.begin();
+             i != duplicates.end(); ++i) {
             LOG_WARN(logger, MSG_DUPMSGID).arg(*i);
         }
 
@@ -121,10 +121,10 @@ LoggerManager::readLocalMessageFile(const char* file) {
         logger.info(MSG_RDLOCMES).arg(file);
         reader.readFile(file, MessageReader::REPLACE);
 
-        // File successfully read.  As each message in the file is supposed to replace
-        // one in the dictionary, any ID read that can't be located in the dictionary
-        // will not be used.  To aid problem diagnosis, the unknown message IDs are
-        // listed.
+        // File successfully read.  As each message in the file is supposed to
+        // replace one in the dictionary, any ID read that can't be located in
+        // the dictionary will not be used.  To aid problem diagnosis, the
+        // unknown message IDs are listed.
         MessageReader::MessageIDCollection unknown = reader.getNotAdded();
         for (MessageReader::MessageIDCollection::const_iterator
             i = unknown.begin(); i != unknown.end(); ++i) {
@@ -136,8 +136,8 @@ LoggerManager::readLocalMessageFile(const char* file) {
         MessageID ident = e.id();
         vector<string> args = e.arguments();
 
-        // Log the variable number of arguments.  The actual message will be logged
-        // when the error_message variable is destroyed.
+        // Log the variable number of arguments.  The actual message will be
+        // logged when the error_message variable is destroyed.
         Formatter<isc::log::Logger> error_message = logger.error(ident);
         for (int i = 0; i < args.size(); ++i) {
             error_message = error_message.arg(args[i]);

src/lib/log/logger_manager.h

@@ -71,10 +71,13 @@ public:
     /// Performs run-time initialization of the logger system, in particular
     /// supplying the root logger name and name of a replacement message file.
     ///
-    /// This must be the first logging function called in the program.
+    /// This must be the first logging function called in the program.  If
+    /// an attempt is made to log a message before this is function is called,
+    /// the results will be dependent on the underlying logging package.
     ///
-    /// \param root Name of the root logger
-    /// \param file Name of the local message file.
+    /// \param root Name of the root logger.  This can be NULL, but should be
+    ///        set to the name of the program.
+    /// \param file Name of the local message file (if there is one).
     /// \param severity Severity at which to log
     /// \param dbglevel Debug severity (ignored if "severity" is not "DEBUG")
     static void init(const std::string& root, const char* file = NULL,
@@ -100,8 +103,9 @@ private:
     /// \brief Initialize Processing
     ///
     /// Initializes the processing of a list of specifications by resetting all
-    /// loggers to their defaults.  Note that loggers aren't removed as unless
-    /// a previously-enabled logger is re-enabled, it becomes inactive.
+    /// loggers to their defaults, which is to pass the message to their
+    /// parent logger.  (Except for the root logger, where the default action is
+    /// to output the message.)
     void processInit();
 
     /// \brief Process Logging Specification

src/lib/log/logger_manager_impl.h

@@ -78,9 +78,14 @@ public:
 
     /// \brief Implementation-specific initialization
     ///
-    /// Performs any implementation-specific initialization.  It is assumed
-    /// that the name of the BIND 10 root logger can be obtained from the
-    /// global function getRootLoggerName().
+    /// Sets the basic configuration for logging (the root logger has INFO and
+    /// more severe messages routed to stdout).  Unless this function (or
+    /// process() with a valid specification for all loggers that will log
+    /// messages) is called before a message is logged, log4cplus will output
+    /// a message to stderr noting that logging has not been initialized.
+    ///
+    /// It is assumed here that the name of the BIND 10 root logger can be
+    /// obtained from the global function getRootLoggerName().
     ///
     /// \param severity Severity to be associated with this logger
     /// \param dbglevel Debug level associated with the root logger