From 5595a4d215cf614d98af47c76ed7bb1442fc342f Mon Sep 17 00:00:00 2001
From: "Alan D. Salewski" <ads@salewski.email>
Date: Sun, 6 Dec 2020 18:14:37 -0500
Subject: [PATCH] [10 of 10]: docs: explain use of lower case log level names

Since our convention throughout the docs is to use the lower case
form of log level names (e.g., "info" rather than "INFO"), users
might mistakenly infer that we are implying that only the lower case
forms are legit. Careful readers might even suspect that the handful
of departures are typos rather than deliberate examples.

This change adds a blurblet to the README.md and to the top-level
API docs explaining the convention and the motivation for using
it (consistency).
---
 README.md  |  5 +++++
 src/lib.rs | 12 ++++++++----
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 82547f09..bc54171d 100644
--- a/README.md
+++ b/README.md
@@ -57,6 +57,11 @@ $ RUST_LOG=INFO ./main
 [2018-11-03T06:09:06Z INFO  default] starting up
 ```
 
+So which form should you use? For consistency, our convention is to use lower
+case names. Where our docs do use other forms, they do so in the context of
+specific examples, so you won't be surprised if you see similar usage in the
+wild.
+
 The log levels that may be specified correspond to the [`log::Level`][level-enum]
 enum from the `log` crate. They are:
 
diff --git a/src/lib.rs b/src/lib.rs
index d36642dc..284be258 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -120,9 +120,6 @@
 //!    * `debug`
 //!    * `trace`
 //!
-//! The letter case is not significant for the logging level names; e.g.,
-//! `debug`, `DEBUG`, and `dEbuG` all represent the same logging level.
-//!
 //! There is also a pseudo logging level, `off`, which may be specified to
 //! disable all logging for a given module or for the entire application. As
 //! with the logging levels, the letter case is not significant[^fn-off].
@@ -130,6 +127,12 @@
 //! [^fn-off]: Similar to the universe of log level names, the `off` pseudo
 //!    log level feature is also provided by the underlying `log` crate.
 //!
+//! The letter case is not significant for the logging level names; e.g.,
+//! `debug`, `DEBUG`, and `dEbuG` all represent the same logging level. For
+//! consistency, our convention is to use the lower case names. Where our docs
+//! do use other forms, they do so in the context of specific examples, so you
+//! won't be surprised if you see similar usage in the wild.
+//!
 //! As the log level for a module is optional, the module to enable logging for
 //! is also optional. **If only a level is provided, then the global log
 //! level for all modules is set to this value.**
@@ -146,7 +149,8 @@
 //! * `hello,std::option` turns on hello, and std's option logging
 //! * `error,hello=warn` turn on global error logging and also warn for hello
 //! * `error,hello=off`` turn on global error logging, but turn off logging for hello
-//! * `OFF` turns off all logging for the application
+//! * `off` turns off all logging for the application
+//! * `OFF` turns off all logging for the application (same as previous)
 //!
 //! ## Filtering results
 //!