[#2537] document logging inheritance more clearly

diff --git a/doc/sphinx/arm/logging.rst b/doc/sphinx/arm/logging.rst
index 884754520c5537767f7d56d796aae3070e75a540..e631cc93289d716b1d15b34a191079d24960b2cf 100644 (file)
--- a/doc/sphinx/arm/logging.rst
+++ b/doc/sphinx/arm/logging.rst
@@ -101,10 +101,18 @@ logger, whereas any not specified are inherited from it.
 To illustrate this, suppose we are using the DHCPv4 server with the
 root logger ``kea-dhcp4`` logging at the INFO level. In order to enable
 DEBUG verbosity for DHCPv4 packet drops, we must create a configuration
-entry for the logger called "kea-dhcp4.bad-packets” and specify severity
-DEBUG for this logger. All other configuration parameters may be omitted
-for this logger if the logger should use the default values specified in
-the root logger's configuration.
+entry for the logger with ``"name": "kea-dhcp4.bad-packets”``,
+``"severity": "DEBUG"`` and an explicit debug level. All other configuration
+parameters may be omitted for this logger if it should use the default values
+specified in the root logger's configuration.
+
+``debuglevel`` is inherited only if ``severity`` is missing as well. For
+predictable results, if ``severity`` is ``"DEBUG"``, these two attributes
+should always be explicitly specified or omitted together. An entry with an
+explicit ``"DEBUG"`` severity will not inherit ``debuglevel`` from the root
+logger, and will default to ``0`` if missing, resulting in no debug messages
+being logged. This is a consequence of relying on the log4cplus inheritance
+mechanism.
 
 If there are multiple logger specifications in the configuration that
 might match a particular logger, the specification with the more