diff --git a/src/attr_quirk.rs b/src/attr_quirk.rs
index d5b5fff..8a697b8 100644
--- a/src/attr_quirk.rs
+++ b/src/attr_quirk.rs
@@ -17,9 +17,9 @@ use crate::Style;
/// the terminal's configuration. Common attributes, such as `bold`, `dim`,
/// `italic`, `underline`, and `strike` typically have good support and are
/// largely reliable. Less commonly supported attributes like `conceal` and
-/// `invert` will _usually_ be supported by "modern" terminals. Rarely supprted
-/// attributes, like `blink` and `rapid blink` will usually have no effect when
-/// applied.
+/// `invert` will _usually_ be supported by "modern" terminals. Rarely supported
+/// attributes, such as `blink` and `rapid blink`, will typically have no
+/// effect when applied.
///
/// # Example
///
diff --git a/src/condition.rs b/src/condition.rs
index 85a9719..6444c17 100644
--- a/src/condition.rs
+++ b/src/condition.rs
@@ -57,7 +57,7 @@ use core::sync::atomic::{AtomicPtr, Ordering};
///
/// # Custom Conditions
///
-/// Custom, arbitrary conditions can be creared via [`Condition::from()`] or
+/// Custom, arbitrary conditions can be created with [`Condition::from()`] or
/// [`Condition::cached()`].
///
/// ```rust
diff --git a/src/global.rs b/src/global.rs
index 99f13ae..19f5dd5 100644
--- a/src/global.rs
+++ b/src/global.rs
@@ -42,7 +42,7 @@ pub fn enable() {
ENABLED.store(Condition::ALWAYS);
}
-/// Dynamically enables styling globally based on `condition`.
+/// Dynamically enables and disables styling globally based on `condition`.
///
/// `condition` is expected to be fast: it is checked dynamically, each time a
/// [`Painted`](crate::Painted) value is displayed.
diff --git a/src/hyperlink.rs b/src/hyperlink.rs
index 1db75b6..2b0e127 100644
--- a/src/hyperlink.rs
+++ b/src/hyperlink.rs
@@ -2,7 +2,7 @@
//!
//! # Usage
//!
-//! Enable the `hyperlink` crate feature. Enabling the feature implicitly
+//! Enable the `hyperlink` crate feature. Enabling `hyperlink` implicitly
//! enables `std`.
//!
//! Import the `HyperlinkExt` extension trait and use the [`link()`] builder
diff --git a/src/lib.rs b/src/lib.rs
index d798a67..81edfb3 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -75,16 +75,16 @@
//!
//! ## Uniform `const` Builders
//!
-//! The builder methods are uniformly available for [`Style`], [`Color`], and
-//! [`Painted`], which means you can chain calls across library types. They are
-//! also `const`, allowing creations of `const` or `static` styles which can be
-//! directly applied via the [`paint()`](Paint::paint()) method, also from the
-//! [`Paint`] trait and thus available for every type:
+//! All builder methods are uniformly available for [`Style`], [`Color`], and
+//! [`Painted`], which means you can chain calls across library types. All
+//! methods are `const`, allowing creations of `const` or `static` [`Style`]s. A
+//! `Style` can be directly applied to values with [`.paint()`](Paint::paint()),
+//! from [`Paint::paint()`], available for every type:
//!
//! ```rust
//! use yansi::{Paint, Style, Color::*};
//!
-//! // `const` constructors allow static `Style` for easy reuse.
+//! // `const` constructors allow static `Style`s for easy reuse
//! static ALERT: Style = White.bright().underline().italic().on_red();
//!
//! println!("Testing, {}, {}, {}!",
@@ -104,17 +104,18 @@
//!
//! Styling is enabled by default but can be enabled and disabled globally via
//! [`enable()`] and [`disable()`]. When styling is disabled, no ANSI escape
-//! codes are emitted, and [_masked_] values are omitted.
+//! codes are emitted, and [_masked_] values are omitted entirely.
//!
-//! Stying can also be globally enabled _conditionally_ and dynamically via
-//! [`whenever()`] based on an arbitrary [`Condition`]: a function that returns
-//! `true` to enable styling and `false` to disable it. The condition is
-//! evaluated every time a [`Painted`] items is displayed.
+//! Global styling can also be dynamically enabled and disabled using
+//! [`whenever()`] with an arbitrary [`Condition`]: a function that returns
+//! `true` or `false`. This condition is evaluated each time a [`Painted`] item
+//! is displayed. The associated styling is enabled, and mask values emitted,
+//! exactly when and only when the condition returns `true`.
//!
//! ### Per-`Style`
//!
-//! A specific `Style` can also itself be conditionally applied by using
-//! [`whenever()`](Style::whenever()):
+//! A specific `Style` can itself be conditionally applied by using
+//! [`.whenever()`](Style::whenever()):
//!
//! ```rust
//! # #[cfg(feature = "detect-tty")] {
@@ -137,9 +138,10 @@
//!
//! # Quirks
//!
-//! `yansi` implements several "quirks", applicable via [`Quirk`] and the
-//! respective methods, that modify if and how styling is presented to the
-//! terminal. These quirks do not correspond to any ANSI styling sequences.
+//! As a convenience, `yansi` implements several "quirks", applicable via
+//! [`Quirk`] and the respective methods, that modify if and how styling is
+//! presented to the terminal. These quirks do not correspond to any ANSI
+//! styling sequences.
//!
//! ## Masking
//!
@@ -171,11 +173,13 @@
//! [`wrap()`](Painted::wrap()) constructor. A wrapping style modifies any
//! styling resets emitted by the internal value so that they correspond to the
//! wrapping style. In other words, the "reset" style of the wrapped item is
-//! modified to be the wrapping style.
+//! modified to be the style being `.wrap()`d.
//!
-//! It is needed only in situations when styling opaque items or items that may
-//! already be styled, such as when implementing a generic logger. It exists to
-//! enable consistent styling across such items:
+//! Wrapping is useful in situations where opaque and arbitrary values must be
+//! styled consistently irrespective of any existing styling. For example, a
+//! generic logger might want to style messages based on log levels
+//! consistently, even when those messages may already include styling. Wrapping
+//! exists to enable such consistent styling:
//!
//! ```rust
//! use yansi::Paint;
@@ -193,19 +197,19 @@
//! Go
//!
//!
-//! Without wrapping, the `red()` reset after "Stop" is not overwritten:
+//! Without wrapping, the reset after `"Stop".red()` would not be overwritten:
//! `>` Hey! Stop and Go
//!
-//! Wrapping incurs a performance cost via an extra allocation and replacement
-//! if the wrapped item has styling applied to it. Otherwise, it does not
-//! allocate nor incur a meaningful performance cost.
+//! Wrapping incurs a performance cost due to an extra allocation and
+//! replacement if the wrapped item has styling applied to it. Otherwise, it
+//! does not allocate nor incur a meaningful performance cost.
//!
//! ## Lingering
//!
//! Styling can _linger_ beyond a single value via [`Quirk::Linger`] or the
//! equivalent [`linger()`](Painted::linger()) constructor. A lingering style
//! does not clear itself after being applied. In other words, the style lingers
-//! on beyond the value it's applied to and until something else clears the
+//! on beyond the value it's applied to, until something else clears the
//! respective styling.
//!
//! The complement to lingering is force clearing via [`Quirk::Clear`] or the
@@ -272,7 +276,7 @@
//! Most pimrary colors are available in regular and _bright_ variants, e.g.,
//! [`Color::Red`] and [`Color::BrightRed`]. The [`Quirk::Bright`] and
//! [`Quirk::OnBright`] quirks, typically applied via
-//! [`bright()`](Painted::bright()) and [`on_bright()`](Painted::on_bright()),
+//! [`.bright()`](Painted::bright()) and [`.on_bright()`](Painted::on_bright()),
//! provide an alternative, convenient mechanism to select the bright variant of
//! the selected foreground or background color, respectively. The quirk
//! provides no additional colors and is equivalent to selecting the bright
@@ -307,14 +311,14 @@
//! # Windows
//!
//! Styling is supported and enabled automatically on Windows beginning with
-//! the Windows 10 Anniversary Update, or about [95% of all Windows machines
+//! the Windows 10 Anniversary Update, or about [96% of all Windows machines
//! worldwide](https://gs.statcounter.com/os-version-market-share/windows/desktop/worldwide),
//! and likely closer to 100% of developer machines (e.g., 99% of visitors to
//! [rocket.rs](https://rocket.rs) on Windows are on Windows 10+).
//!
//! Yansi enables styling support on Windows by querying the Windows API on the
//! first attempt to color. If support is available, it is enabled. If support
-//! is not available, styling is disabled and no styling is emitted.
+//! is not available, styling is disabled and no styling sequences are emitted.
//!
//! # Crate Features
//!
@@ -326,15 +330,16 @@
//! | `detect-env` | N | `std` | See [optional conditions]. |
//! | `hyperlink` | N | `std` | Enables [hyperlinking] support. |
//!
-//! With `no-default-features = true`, this crate is `#[no_std]`.
+//! With `default-features = false`, this crate is `#[no_std]`.
//!
//! Without any features enabled, all functionality except [wrapping] is
-//! available. To recover wrapping _with_ `#[no_std]`, set `no-default-features
-//! = false` and enable the `alloc` feature, which requires `alloc` support.
+//! available. To recover wrapping _with_ `#[no_std]`, set `default-features =
+//! false` and enable the `alloc` feature, which requires `alloc` support.
//!
//! [optional conditions]: Condition#built-in-conditions
//! [wrapping]: #wrapping
+#![doc(html_logo_url = "https://raw.githubusercontent.com/SergioBenitez/yansi/master/.github/yansi-logo.png")]
#![cfg_attr(not(feature = "std"), no_std)]
#![cfg_attr(feature = "_nightly", feature(doc_cfg))]
#![deny(missing_docs)]
diff --git a/src/paint.rs b/src/paint.rs
index 4ddf738..a608a15 100644
--- a/src/paint.rs
+++ b/src/paint.rs
@@ -38,9 +38,57 @@ pub struct Painted {
pub style: Style,
}
-/// A trait to apply styling to any value, implemented for all types.
+/// A trait to apply styling to any value. Implemented for all types.
///
-/// See the [crate level docs](crate#usage) for usage details.
+/// Because this trait is implemented for all types, you can use its methods on
+/// any type. With the exception of one constructor method, [`Paint::new()`],
+/// all methods are called with method syntax:
+///
+/// ```rust
+/// use yansi::Paint;
+///
+/// "hello".green(); // calls `Paint::<&'static str>::green()`.
+/// "hello".strike(); // calls `Paint::<&'static str>::strike()`.
+/// 1.on_red(); // calls `Paint::::red()`.
+/// 1.blink(); // calls `Paint::::blink()`.
+/// ```
+///
+/// ### Chaining
+///
+/// All methods return a [`Painted`] whose methods are exactly those of `Paint`.
+/// This means you can chain `Paint` method calls:
+///
+/// ```rust
+/// use yansi::Paint;
+///
+/// "hello".green().strike(); // calls `Paint::green()` then `Painted::strike()`.
+/// 1.on_red().blink(); // calls `Paint::red()` + `Painted::blink()`.
+/// ```
+///
+/// ### Borrow vs. Owned Receiver
+///
+/// The returned [`Painted`] type contains a borrow to the receiver:
+///
+/// ```rust
+/// use yansi::{Paint, Painted};
+///
+/// let v: Painted<&i32> = 1.red();
+/// ```
+///
+/// This is nearly always what you want. In the exceedingly rare case that you
+/// _do_ want `Painted` to own its value, use [`Paint::new()`] or the equivalent
+/// [`Painted::new()`]:
+///
+/// ```rust
+/// use yansi::{Paint, Painted};
+///
+/// let v: Painted = Paint::new(1);
+/// let v: Painted = Painted::new(1);
+/// ```
+///
+/// ### Further Details
+///
+/// See the [crate level docs](crate#usage) for more details and examples.
pub trait Paint {
/// Create a new [`Painted`] with a default [`Style`].
///