[ovs-dev] [vlog-levels 2/2] vlog: Move log level definitions from source code to user documentation.

[Ben Pfaff]

Users should be able to find out what a log level means without reading
source code comments, so this seems like a better place for it.
---
 lib/vlog.h                |   20 +-------------------
 lib/vlog.man              |    3 ++-
 utilities/ovs-appctl.8.in |   33 ++++++++++++++++++++++++++++++++-
 3 files changed, 35 insertions(+), 21 deletions(-)

diff --git a/lib/vlog.h b/lib/vlog.h
index 5462bc5..6148203 100644
--- a/lib/vlog.h
+++ b/lib/vlog.h
@@ -30,25 +30,7 @@ extern "C" {
 
 /* Logging importance levels.
  *
- * The following log levels, in descending order of importance, are enabled by
- * default:
- *
- *   - OFF: Not currently used.
- *
- *   - ERR: A high-level operation or a subsystem failed.  Attention is
- *     warranted.
- *
- *   - WARN: A low-level operation failed, but higher-level subsystems may be
- *     able to recover.
- *
- *   - INFO: Information that may be useful in retrospect when investigating
- *     a problem.
- *
- * The lowest log level is not enabled by default:
- *
- *   - DBG: Information useful only to someone with intricate knowledge of the
- *     system, or that would commonly cause too-voluminous log output.
- */
+ * ovs-appctl(8) defines each of the log levels. */
 #define VLOG_LEVELS                             \
     VLOG_LEVEL(OFF, LOG_ALERT)                  \
     VLOG_LEVEL(ERR, LOG_ERR)                    \
diff --git a/lib/vlog.man b/lib/vlog.man
index 993babd..08dbc41 100644
--- a/lib/vlog.man
+++ b/lib/vlog.man
@@ -24,7 +24,8 @@ below).
 \fIlevel\fR must be one of \fBoff\fR, \fBerr\fR, \fBwarn\fR,
 \fBinfo\fR, or
 \fBdbg\fR, designating the minimum severity of a message for it to be
-logged.  If it is omitted, \fIlevel\fR defaults to \fBdbg\fR.
+logged.  If it is omitted, \fIlevel\fR defaults to \fBdbg\fR.  See
+\fBovs\-appctl\fR(8) for a definition of each log level.
 .RE
 .
 .TP
diff --git a/utilities/ovs-appctl.8.in b/utilities/ovs-appctl.8.in
index 55f919c..2c0deb1 100644
--- a/utilities/ovs-appctl.8.in
+++ b/utilities/ovs-appctl.8.in
@@ -55,9 +55,40 @@ as if it had been specified directly as the target.
 The default target is \fBovs\-vswitchd\fR.
 .
 .SH LOGGING COMMANDS
+.
+.PP
+Open vSwitch has several log levels.  The highest-severity log level
+is:
+.
+.IP "\fBOFF\fR"
+No message is ever logged at this level, so setting a logging
+facility's log level to \fBOFF\fR disables logging to that facility.
+.
+.PP
+The following log levels, in order of descending severity, are enabled
+by default:
+.
+.IP "\fBERR\fR"
+A high-level operation or a subsystem failed.  Attention is
+warranted.
+.IP "\fBWARN\fR"
+A low-level operation failed, but higher-level subsystems may be able
+to recover.
+.IP "\fBINFO\fR"
+Information that may be useful in retrospect when investigating
+a problem.
+.
+.PP
+The lowest log level is not enabled by default:
+.
+.IP "\fBDBG\fR"
+Information useful only to someone with intricate knowledge of the
+system, or that would commonly cause too-voluminous log output.  Log
+messages at this level are not logged by default.
+.
+.PP
 Every Open vSwitch daemon supports the following commands for
 examining and adjusting log levels.
-.
 .IP "\fBvlog/list\fR"
 Lists the known logging modules and their current levels.
 .
-- 
1.7.4.4