From 2eff19fc1bb9df46f93e01b6e27ce9ff4294a70d Mon Sep 17 00:00:00 2001 From: Ed Page Date: Thu, 9 Nov 2023 20:20:20 -0600 Subject: [PATCH] docs(ref): Improve scannability of RUST_LOG docs Fixes #281 --- src/lib.rs | 83 +++++++++++++++++++++++------------------------------- 1 file changed, 36 insertions(+), 47 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 92eeea20..c2b27faf 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -85,78 +85,67 @@ //! //! ## Enabling logging //! -//! Log levels are controlled on a per-module basis, and **by default all -//! logging is disabled except for the `error` level**. +//! **By default all logging is disabled except for the `error` level** //! -//! Logging is controlled via the **`RUST_LOG`** environment variable. The -//! value of this environment variable is a comma-separated list of *logging -//! directives*. A logging directive is of the form: +//! The **`RUST_LOG`** environment variable controls logging with the syntax: +//! ```text +//! RUST_LOG=[target][=][level][,...] +//! ``` +//! Or in other words, its a comma-separated list of directives. +//! Directives can filter by **target**, by **level**, or both (using `=`). //! +//! For example, //! ```text -//! example::log::target=level +//! RUST_LOG=data=debug,hardware=debug //! ``` //! -//! The log target is typically equal to the path of the module the message +//! **target** is typically the path of the module the message //! in question originated from, though it can be overridden. -//! //! The path is rooted in the name of the crate it was compiled for, so if //! your program is in a file called, for example, `hello.rs`, the path would //! simply be `hello`. //! //! Furthermore, the log can be filtered using prefix-search based on the -//! specified log target. A value of, for example, `RUST_LOG=example`, would -//! match all of the messages with targets: +//! specified log target. //! -//! * `example` -//! * `example::test` -//! * `example::test::module::submodule` -//! * `examples::and_more_examples` +//! For example, `RUST_LOG=example` would match the following targets: +//! - `example` +//! - `example::test` +//! - `example::test::module::submodule` +//! - `examples::and_more_examples` //! //! When providing the crate name or a module path, explicitly specifying the //! log level is optional. If omitted, all logging for the item will be //! enabled. //! -//! The names of the log levels that may be specified correspond to the -//! variations of the [`log::Level`][level-enum] enum from the `log` -//! crate. They are: -//! -//! * `error` -//! * `warn` -//! * `info` -//! * `debug` -//! * `trace` +//! **level** is the maximum [`log::Level`][level-enum] to be shown and includes: +//! - `error` +//! - `warn` +//! - `info` +//! - `debug` +//! - `trace` +//! - `off` (pseudo level to disable all logging for the target) //! -//! 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. -//! -//! The letter case is not significant for the logging level names; e.g., +//! Logging level names are case-insensitive; 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.** -//! //! 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 -//! * `OFF` turns off all logging for the application (same as previous) +//! - `RUST_LOG=hello` turns on all logging for the `hello` module +//! - `RUST_LOG=trace` turns on all logging for the application, regardless of its name +//! - `RUST_LOG=TRACE` turns on all logging for the application, regardless of its name (same as previous) +//! - `RUST_LOG=info` turns on all info logging +//! - `RUST_LOG=INFO` turns on all info logging (same as previous) +//! - `RUST_LOG=hello=debug` turns on debug logging for `hello` +//! - `RUST_LOG=hello=DEBUG` turns on debug logging for `hello` (same as previous) +//! - `RUST_LOG=hello,std::option` turns on `hello`, and std's option logging +//! - `RUST_LOG=error,hello=warn` turn on global error logging and also warn for `hello` +//! - `RUST_LOG=error,hello=off` turn on global error logging, but turn off logging for `hello` +//! - `RUST_LOG=off` turns off all logging for the application +//! - `RUST_LOG=OFF` turns off all logging for the application (same as previous) //! //! ## Filtering results //!