Merge pull request #111 from KodrAus/chore/docs

Tidy up some docs

Author: KodrAus

.travis.yml

@@ -9,6 +9,7 @@ before_script:
   - pip install 'travis-cargo<0.2' --user && export PATH=$HOME/.local/bin:$PATH
 script:
   - cargo run -p ci
+  - cargo run --example default
 after_success:
   - travis-cargo --only nightly doc-upload
 

README.md

@@ -93,11 +93,11 @@ $ RUST_LOG=my_lib=info cargo test
      Running target/debug/my_lib-...
 
 running 2 tests
-[2017-11-09T02:12:24Z INFO my_lib::tests] logging from another test
-[2017-11-09T02:12:24Z INFO my_lib] add_one called with -8
+[INFO my_lib::tests] logging from another test
+[INFO my_lib] add_one called with -8
 test tests::it_handles_negative_numbers ... ok
-[2017-11-09T02:12:24Z INFO my_lib::tests] can log from the test too
-[2017-11-09T02:12:24Z INFO my_lib] add_one called with 2
+[INFO my_lib::tests] can log from the test too
+[INFO my_lib] add_one called with 2
 test tests::it_adds_one ... ok
 
 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured
@@ -115,8 +115,8 @@ $ RUST_LOG=my_lib=info cargo test it_adds_one
      Running target/debug/my_lib-...
 
 running 1 test
-[2017-11-09T02:12:24Z INFO my_lib::tests] can log from the test too
-[2017-11-09T02:12:24Z INFO my_lib] add_one called with 2
+[INFO my_lib::tests] can log from the test too
+[INFO my_lib] add_one called with 2
 test tests::it_adds_one ... ok
 
 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
@@ -131,11 +131,9 @@ you can use the `Builder` to change the log target:
 use std::env;
 use env_logger::{Builder, Target};
 
-let mut builder = Builder::new();
+let mut builder = Builder::from_default_env();
 builder.target(Target::Stdout);
-if env::var("RUST_LOG").is_ok() {
-    builder.parse(&env::var("RUST_LOG").unwrap());
-}
+
 builder.init();
 ```
 

src/fmt/mod.rs

@@ -46,7 +46,7 @@ pub use self::writer::glob::*;
 use self::writer::{Writer, Buffer};
 
 pub(crate) mod glob {
-    pub use super::{Target, WriteStyle, Formatter};
+    pub use super::{Target, WriteStyle};
 }
 
 /// A formatter to write logs into.
@@ -56,7 +56,8 @@ pub(crate) mod glob {
 ///
 /// # Examples
 ///
-/// Use the [`writeln`] macro to easily format a log record:
+/// Use the [`writeln`] macro to format a log record.
+/// An instance of a `Formatter` is passed to an `env_logger` format as `buf`:
 ///
 /// ```
 /// use std::io::Write;
@@ -172,6 +173,9 @@ type SubtleStyle = StyledValue<'static, &'static str>;
 #[cfg(not(feature = "termcolor"))]
 type SubtleStyle = &'static str;
 
+/// The default format.
+/// 
+/// This format needs to work with any combination of crate features.
 struct DefaultFormat<'a> {
     timestamp: bool,
     module_path: bool,

src/fmt/writer/termcolor/extern_impl.rs

@@ -52,8 +52,8 @@ impl Formatter {
     pub fn default_level_style(&self, level: Level) -> Style {
         let mut level_style = self.style();
         match level {
-            Level::Trace => level_style.set_color(Color::White),
-            Level::Debug => level_style.set_color(Color::Black).set_intense(true),
+            Level::Trace => level_style.set_color(Color::Black).set_intense(true),
+            Level::Debug => level_style.set_color(Color::White),
             Level::Info => level_style.set_color(Color::Green),
             Level::Warn => level_style.set_color(Color::Yellow),
             Level::Error => level_style.set_color(Color::Red).set_bold(true),
@@ -332,7 +332,7 @@ impl Style {
     }
 
     /// Wrap a value in the style by taking ownership of it.
-    pub fn into_value<T>(&mut self, value: T) -> StyledValue<'static, T> {
+    pub(crate) fn into_value<T>(&mut self, value: T) -> StyledValue<'static, T> {
         StyledValue {
             style: Cow::Owned(self.clone()),
             value

src/lib.rs

@@ -157,24 +157,11 @@
 //! The following example excludes the timestamp from the log output:
 //! 
 //! ```
-//! #[macro_use] extern crate log;
-//! extern crate env_logger;
-//!
-//! use log::Level;
-//!
-//! fn main() {
-//!     env_logger::Builder::from_default_env()
-//!         .default_format_timestamp(false)
-//!         .init();
+//! use env_logger::Builder;
 //!
-//!     debug!("this is a debug {}", "message");
-//!     error!("this is printed by default");
-//!
-//!     if log_enabled!(Level::Info) {
-//!         let x = 3 * 4; // expensive computation
-//!         info!("the answer was: {}", x);
-//!     }
-//! }
+//! Builder::from_default_env()
+//!     .default_format_timestamp(false)
+//!     .init();
 //! ```
 //! 
 //! ### Stability of the default format
@@ -186,6 +173,24 @@
 //! If you want to capture or interpret the output of `env_logger` programmatically 
 //! then you should use a custom format.
 //! 
+//! ### Using a custom format
+//! 
+//! Custom formats can be provided as closures to the [`Builder`].
+//! These closures take a [`Formatter`] and `log::Record` as arguments:
+//! 
+//! ```
+//! use std::io::Write;
+//! use env_logger::Builder;
+//!
+//! Builder::from_default_env()
+//!     .format(|buf, record| {
+//!         writeln!(buf, "{}: {}", record.level(), record.args())
+//!     })
+//!     .init();
+//! ```
+//! 
+//! See the [`fmt`] module for more details about custom formats.
+//! 
 //! ## Specifying defaults for environment variables
 //! 
 //! `env_logger` can read configuration from environment variables.
@@ -194,22 +199,15 @@
 //! isn't set:
 //! 
 //! ```
-//! #[macro_use] extern crate log;
-//! extern crate env_logger;
+//! use env_logger::{Builder, Env};
 //!
-//! use log::Level;
-//!
-//! fn main() {
-//!     let env = env_logger::Env::default()
-//!         .filter_or(env_logger::DEFAULT_FILTER_ENV, "warn");
-//! 
-//!     env_logger::Builder::from_env(env).init();
-//! }
+//! Builder::from_env(Env::default().default_filter_or("warn")).init();
 //! ```
 //! 
 //! [log-crate-url]: https://docs.rs/log/
 //! [`Builder`]: struct.Builder.html
 //! [`Env`]: struct.Env.html
+//! [`fmt`]: fmt/index.html
 
 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
        html_favicon_url = "http://www.rust-lang.org/favicon.ico",
@@ -244,6 +242,7 @@ pub mod fmt;
 pub use self::fmt::glob::*;
 
 use self::filter::Filter;
+use self::fmt::Formatter;
 use self::fmt::writer::{self, Writer};
 
 /// The default name for the environment variable to read filters from.
@@ -457,7 +456,7 @@ impl Builder {
     /// 
     /// let mut builder = Builder::new();
     /// 
-    /// builder.format(|buf, record| write!(buf, "{}", record.args()));
+    /// builder.format(|buf, record| writeln!(buf, "{}", record.args()));
     /// ```
     ///
     /// [`Formatter`]: fmt/struct.Formatter.html
@@ -836,6 +835,18 @@ impl<'a> Env<'a> {
         self
     }
 
+    /// Use the default environment variable to read the filter from.
+    /// 
+    /// If the variable is not set, the default value will be used.
+    pub fn default_filter_or<V>(mut self, default: V) -> Self
+    where
+        V: Into<Cow<'a, str>>,
+    {
+        self.filter = Var::new_with_default(DEFAULT_FILTER_ENV, default);
+
+        self
+    }
+
     fn get_filter(&self) -> Option<String> {
         self.filter.get()
     }
@@ -863,6 +874,18 @@ impl<'a> Env<'a> {
         self
     }
 
+    /// Use the default environment variable to read the style from.
+    ///
+    /// If the variable is not set, the default value will be used.
+    pub fn default_write_style_or<V>(mut self, default: V) -> Self
+        where
+            V: Into<Cow<'a, str>>,
+    {
+        self.write_style = Var::new_with_default(DEFAULT_WRITE_STYLE_ENV, default);
+
+        self
+    }
+
     fn get_write_style(&self) -> Option<String> {
         self.write_style.get()
     }