Merge pull request #263 from sfackler/docs-fix

Fix max log level documentation

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<Log>` 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<Log>` 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<F>(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"))