From 484ca2b2f5e0689822cb173108476dd1871cfa86 Mon Sep 17 00:00:00 2001
From: "Alan D. Salewski" <ads@salewski.email>
Date: Sat, 5 Dec 2020 05:08:56 -0500
Subject: [PATCH] [08 of 10]: document 'OFF' pseudo log level feature

---
 README.md  |  4 ++++
 src/lib.rs | 11 +++++++++++
 2 files changed, 15 insertions(+)

diff --git a/README.md b/README.md
index 77b8fc57..82547f09 100644
--- a/README.md
+++ b/README.md
@@ -68,6 +68,10 @@ enum from the `log` crate. They are:
 
 [level-enum]:  https://docs.rs/log/latest/log/enum.Level.html  "log::Level (docs.rs)"
 
+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.
+
 `env_logger` can be configured in other ways besides an environment variable. See [the examples](https://github.com/env-logger-rs/env_logger/tree/master/examples) for more approaches.
 
 ### In tests
diff --git a/src/lib.rs b/src/lib.rs
index 6439cde7..9a30d695 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -123,6 +123,13 @@
 //! 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].
+//!
+//! [^fn-off]: Similar to the universe of log level names, the `off` pseudo
+//!    log level feature is also provided by the underlying `log` crate.
+//!
 //! 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.**
@@ -130,12 +137,16 @@
 //! Some examples of valid values of `RUST_LOG` are:
 //!
 //! * `hello` turns on all logging for the 'hello' module
+//! * `trace` turns on all logging for the application, regardless of its name
+//! * `TRACE` turns on all logging for the application, regardless of its name (same as previous)
 //! * `info` turns on all info logging
 //! * `INFO` turns on all info logging (same as previous)
 //! * `hello=debug` turns on debug logging for 'hello'
 //! * `hello=DEBUG` turns on debug logging for 'hello' (same as previous)
 //! * `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
 //!
 //! ## Filtering results
 //!