From bdff1b0fd8841eb9ba90ffb1fb512b27cd394a48 Mon Sep 17 00:00:00 2001 From: Steven Fackler Date: Fri, 9 Feb 2018 21:53:51 -0800 Subject: [PATCH] Fix max log level documentation Closes #259 --- src/lib.rs | 58 +++++++++++++++++++++++++++++------------------------- 1 file changed, 31 insertions(+), 27 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index e68cf40..5609848 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -138,16 +138,16 @@ //! # fn main() {} //! ``` //! -//! Loggers are installed by calling the [`set_logger`] function. It takes a -//! closure which is provided a [`MaxLevelFilter`] token and returns a -//! [`Log`] trait object. The [`MaxLevelFilter`] token controls the global -//! maximum log level. The logging facade uses this as an optimization to -//! improve performance of log messages at levels that are disabled. In the -//! case of our example logger, we'll want to set the maximum log level to -//! [`Info`][level_link], since we ignore any [`Debug`][level_link] or -//! [`Trace`][level_link] level log messages. A logging implementation -//! should provide a function that wraps a call to [`set_logger`], handling -//! initialization of the logger: +//! Loggers are installed by calling the [`set_logger`] function. The maximum +//! log level also needs to be adjusted via the [`set_max_level`] function. The +//! logging facade uses this as an optimization to improve performance of log +//! messages at levels that are disabled. It's important to set it, as it +//! defaults to [`Off`][filter_link], so no log messages will ever be captured! +//! In the case of our example logger, we'll want to set the maximum log level +//! to [`Info`][filter_link], since we ignore any [`Debug`][level_link] or +//! [`Trace`][level_link] level log messages. A logging implementation should +//! provide a function that wraps a call to [`set_logger`] and +//! [`set_max_level`], handling initialization of the logger: //! //! ```rust //! # extern crate log; @@ -165,16 +165,20 @@ //! //! pub fn init() -> Result<(), SetLoggerError> { //! log::set_logger(&LOGGER) +//! .map(|()| log::set_max_level(LevelFilter::Info)) //! } //! ``` //! +//! Implementations that adjust their configurations at runtime should take care +//! to adjust the maximum log level as well. +//! //! # Use with `std` //! -//! `set_logger` requires you to provide a `&'static Log`, which can be hard if -//! your logger depends on some runtime configuration. The `set_boxed_logger` -//! function is available with the `std` Cargo feature. It is identical to -//! `set_logger` except that it requires you to provide a `Box` rather than -//! a `&'static Log`: +//! `set_logger` requires you to provide a `&'static Log`, which can be hard to +//! obtain if your logger depends on some runtime configuration. The +//! `set_boxed_logger` function is available with the `std` Cargo feature. It is +//! identical to `set_logger` except that it takes a `Box` rather than a +//! `&'static Log`: //! //! ```rust //! # extern crate log; @@ -189,6 +193,7 @@ //! # #[cfg(feature = "std")] //! pub fn init() -> Result<(), SetLoggerError> { //! log::set_boxed_logger(Box::new(SimpleLogger)) +//! .map(|()| log::set_max_level(LevelFilter::Info)) //! } //! ``` //! @@ -232,8 +237,9 @@ //! //! [`Log`]: trait.Log.html //! [level_link]: enum.Level.html +//! [filter_link]: enum.LevelFilter.html //! [`set_logger`]: fn.set_logger.html -//! [`MaxLevelFilter`]: struct.MaxLevelFilter.html +//! [`set_max_level`]: fn.set_max_level.html //! [`try_set_logger_raw`]: fn.try_set_logger_raw.html //! [`shutdown_logger_raw`]: fn.shutdown_logger_raw.html //! [env_logger]: https://docs.rs/env_logger/*/env_logger/ @@ -252,9 +258,7 @@ html_root_url = "https://docs.rs/log/0.4.1")] #![warn(missing_docs)] #![deny(missing_debug_implementations)] - #![cfg_attr(not(feature = "std"), no_std)] - // When compiled for the rustc compiler itself we want to make sure that this is // an unstable crate #![cfg_attr(rustbuild, feature(staged_api, rustc_private))] @@ -272,7 +276,7 @@ use std::error; use std::fmt; use std::mem; use std::str::FromStr; -use std::sync::atomic::{AtomicUsize, ATOMIC_USIZE_INIT, Ordering}; +use std::sync::atomic::{AtomicUsize, Ordering, ATOMIC_USIZE_INIT}; #[macro_use] mod macros; @@ -295,9 +299,9 @@ static MAX_LOG_LEVEL_FILTER: AtomicUsize = ATOMIC_USIZE_INIT; static LOG_LEVEL_NAMES: [&'static str; 6] = ["OFF", "ERROR", "WARN", "INFO", "DEBUG", "TRACE"]; static SET_LOGGER_ERROR: &'static str = "attempted to set a logger after the logging system was \ - already initialized"; + already initialized"; static LEVEL_PARSE_ERROR: &'static str = "attempted to convert a string that doesn't match an \ - existing log level"; + existing log level"; /// An enum representing the available verbosity levels of the logger. /// @@ -390,9 +394,9 @@ fn eq_ignore_ascii_case(a: &str, b: &str) -> bool { } if a.len() == b.len() { - a.bytes().zip(b.bytes()).all(|(a, b)| { - to_ascii_uppercase(a) == to_ascii_uppercase(b) - }) + a.bytes() + .zip(b.bytes()) + .all(|(a, b)| to_ascii_uppercase(a) == to_ascii_uppercase(b)) } else { false } @@ -1048,7 +1052,7 @@ pub fn set_logger(logger: &'static Log) -> Result<(), SetLoggerError> { fn set_logger_inner(make_logger: F) -> Result<(), SetLoggerError> where - F: FnOnce() -> &'static Log + F: FnOnce() -> &'static Log, { unsafe { if STATE.compare_and_swap(UNINITIALIZED, INITIALIZING, Ordering::SeqCst) != UNINITIALIZED { @@ -1253,7 +1257,7 @@ mod tests { assert_eq!( e.description(), "attempted to set a logger after the logging system \ - was already initialized" + was already initialized" ); } @@ -1321,7 +1325,7 @@ mod tests { #[test] fn test_record_complete_builder() { - use super::{Record, Level}; + use super::{Level, Record}; let target = "myApp"; let record_test = Record::builder() .module_path(Some("foo"))