fix a few doc errors

Author: KodrAus

examples/custom_format.rs

@@ -7,10 +7,11 @@ Before running this example, try setting the `MY_LOG_LEVEL` environment variable
 $ export MY_LOG_LEVEL='info'
 ```
 
-Also try setting the `MY_LOG_STYLE` environment variable to `0` to disable colors:
+Also try setting the `MY_LOG_STYLE` environment variable to `never` to disable colors
+or `auto` to enable them:
 
 ```no_run,shell
-$ export MY_LOG_STYLE=0
+$ export MY_LOG_STYLE=never
 ```
 
 If you want to control the logging output completely, see the `custom_logger` example.

examples/custom_logger.rs

@@ -7,10 +7,11 @@ Before running this example, try setting the `MY_LOG_LEVEL` environment variable
 $ export MY_LOG_LEVEL='info'
 ```
 
-Also try setting the `RUST_LOG_STYLE` environment variable to `0` to disable colors:
+Also try setting the `MY_LOG_STYLE` environment variable to `never` to disable colors
+or `auto` to enable them:
 
 ```no_run,shell
-$ export RUST_LOG_STYLE=0
+$ export MY_LOG_STYLE=never
 ```
 
 If you only want to change the way logs are formatted, look at the `custom_format` example.

examples/default.rs

@@ -7,10 +7,11 @@ Before running this example, try setting the `MY_LOG_LEVEL` environment variable
 $ export MY_LOG_LEVEL='info'
 ```
 
-Also try setting the `RUST_LOG_STYLE` environment variable to `0` to disable colors:
+Also try setting the `MY_LOG_STYLE` environment variable to `never` to disable colors
+or `auto` to enable them:
 
 ```no_run,shell
-$ export RUST_LOG_STYLE=0
+$ export MY_LOG_STYLE=never
 ```
 */
 

src/fmt.rs

@@ -5,7 +5,33 @@
 //! about the contents of this module and can use the `Formatter` like an ordinary
 //! [`Write`].
 //! 
+//! # Formatting log records
+//! 
+//! The format used to print log records can be customised using the [`Builder.format`]
+//! method.
+//! Custom formats can apply different color and weight to printed values using
+//! [`Style`] builders.
+//! 
+//! ```
+//! use std::io::Write;
+//! use env_logger::fmt::Color;
+//! 
+//! let mut builder = env_logger::Builder::new();
+//! 
+//! builder.format(|buf, record| {
+//!     let mut level_style = buf.style();
+//! 
+//!     level_style.set_color(Color::Red).set_bold(true);
+//! 
+//!     writeln!(buf, "{}: {}",
+//!         level_style.value(record.level()),
+//!         record.args())
+//! });
+//! ```
+//! 
 //! [`Formatter`]: struct.Formatter.html
+//! [`Style`]: struct.Style.html
+//! [`Builder.format`]: ../struct.Builder.html#method.format
 //! [`Write`]: https://doc.rust-lang.org/stable/std/io/trait.Write.html
 
 use std::io::prelude::*;
@@ -111,7 +137,16 @@ pub struct StyledValue<'a, T> {
     value: T,
 }
 
-/// Log target, either stdout or stderr.
+/// An [RFC3339] formatted timestamp.
+/// 
+/// The timestamp implements [`Display`] and can be written to a [`Formatter`].
+/// 
+/// [RFC3339]: https://www.ietf.org/rfc/rfc3339.txt
+/// [`Display`]: https://doc.rust-lang.org/stable/std/fmt/trait.Display.html
+/// [`Formatter`]: struct.Formatter.html
+pub struct Timestamp(DateTime<Utc>);
+
+/// Log target, either `stdout` or `stderr`.
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 pub enum Target {
     /// Logs will be sent to standard output.
@@ -131,7 +166,7 @@ impl Default for Target {
 pub enum WriteStyle {
     /// Try to print styles, but don't force the issue.
     Auto,
-    /// Always print styles.
+    /// Try very hard to print styles.
     Always,
     /// Never print styles.
     Never,
@@ -143,35 +178,48 @@ impl Default for WriteStyle {
     }
 }
 
+/// A terminal target with color awareness.
 pub(crate) struct Writer(BufferWriter);
 
+/// A builder for a terminal writer.
+/// 
+/// The target and style choice can be configured before building.
 pub(crate) struct Builder {
     target: Target,
     write_style: WriteStyle,
 }
 
 impl Builder {
+    /// Initialize the writer builder with defaults.
     pub fn new() -> Self {
         Builder {
             target: Default::default(),
             write_style: Default::default(),
         }
     }
 
+    /// Set the target to write to.
     pub fn target(&mut self, target: Target) -> &mut Self {
         self.target = target;
         self
     }
 
+    /// Parses a style choice string.
+    /// 
+    /// See the [Disabling colors] section for more details.
+    /// 
+    /// [Disabling colors]: ../index.html#disabling-colors
     pub fn parse(&mut self, write_style: &str) -> &mut Self {
         self.write_style(parse_write_style(write_style))
     }
 
+    /// Whether or not to print style characters when writing.
     pub fn write_style(&mut self, write_style: WriteStyle) -> &mut Self {
         self.write_style = write_style;
         self
     }
 
+    /// Build a terminal writer.
     pub fn build(&mut self) -> Writer {
         let color_choice = match self.write_style {
             WriteStyle::Auto => ColorChoice::Auto,
@@ -304,15 +352,6 @@ impl Style {
     }
 }
 
-/// An [RFC3339] formatted timestamp.
-/// 
-/// The timestamp implements [`Display`] and can be written to a [`Formatter`].
-/// 
-/// [RFC3339]: https://www.ietf.org/rfc/rfc3339.txt
-/// [`Display`]: https://doc.rust-lang.org/stable/std/fmt/trait.Display.html
-/// [`Formatter`]: struct.Formatter.html
-pub struct Timestamp(DateTime<Utc>);
-
 impl Formatter {
     pub(crate) fn new(writer: &Writer) -> Self {
         Formatter {

src/lib.rs

@@ -130,13 +130,14 @@
 //! ## Disabling colors
 //! 
 //! Colors and other styles can be configured with the `RUST_LOG_STYLE`
-//! environment variable.
-//! It accepts the following values:
+//! environment variable. It accepts the following values:
 //! 
 //! * `auto` (default) will attempt to print style characters, but don't force the issue.
+//! If the console isn't available on Windows, or if TERM=dumb, for example, then don't print colors.
 //! * `always` will always print style characters even if they aren't supported by the terminal.
+//! This includes emitting ANSI colors on Windows if the console API is unavailable.
 //! * `never` will never print style characters.
-//!
+//! 
 //! [log-crate-url]: https://docs.rs/log/
 
 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
@@ -281,6 +282,32 @@ impl Builder {
     }
 
     /// Initializes the log builder from the environment.
+    /// 
+    /// The variables used to read configuration from can be tweaked before
+    /// passing in.
+    /// 
+    /// # Examples
+    /// 
+    /// Initialise a logger using the default environment variables:
+    /// 
+    /// ```
+    /// use env_logger::{Builder, Env};
+    /// 
+    /// let mut builder = Builder::from_env(Env::default());
+    /// builder.init();
+    /// ```
+    /// 
+    /// Initialise a logger using the `MY_LOG` variable for filtering and
+    /// `MY_LOG_STYLE` for whether or not to write styles:
+    /// 
+    /// ```
+    /// use env_logger::{Builder, Env};
+    /// 
+    /// let env = Env::new().filter("MY_LOG").write_style("MY_LOG_STYLE");
+    /// 
+    /// let mut builder = Builder::from_env(env);
+    /// builder.init();
+    /// ```
     pub fn from_env<'a, E>(env: E) -> Self
     where
         E: Into<Env<'a>>
@@ -564,10 +591,29 @@ pub fn init() {
 }
 
 /// Attempts to initialize the global logger with an env logger from the given
-/// environment variable.
+/// environment variables.
 ///
 /// This should be called early in the execution of a Rust program. Any log
 /// events that occur before initialization will be ignored.
+/// 
+/// # Examples
+/// 
+/// Initialise a logger using the `MY_LOG` environment variable for filters
+/// and `MY_LOG_STYLE` for writing colors:
+/// 
+/// ```
+/// # extern crate env_logger;
+/// use env_logger::{Builder, Env};
+/// 
+/// # fn run() -> Result<(), Box<::std::error::Error>> {
+/// let env = Env::new().filter("MY_LOG").write_style("MY_LOG_STYLE");
+/// 
+/// env_logger::try_init_from_env(env)?;
+/// 
+/// Ok(())
+/// # }
+/// # fn main() { run().unwrap(); }
+/// ```
 ///
 /// # Errors
 ///
@@ -583,10 +629,23 @@ where
 }
 
 /// Initializes the global logger with an env logger from the given environment
-/// variable.
+/// variables.
 ///
 /// This should be called early in the execution of a Rust program. Any log
 /// events that occur before initialization will be ignored.
+/// 
+/// # Examples
+/// 
+/// Initialise a logger using the `MY_LOG` environment variable for filters
+/// and `MY_LOG_STYLE` for writing colors:
+/// 
+/// ```
+/// use env_logger::{Builder, Env};
+/// 
+/// let env = Env::new().filter("MY_LOG").write_style("MY_LOG_STYLE");
+/// 
+/// env_logger::init_from_env(env);
+/// ```
 ///
 /// # Panics
 ///