From 3e01eaef502d0ee09fbc551409ae6ce400c77868 Mon Sep 17 00:00:00 2001 From: Sergio Benitez Date: Tue, 5 Mar 2024 23:28:27 -0800 Subject: [PATCH] Fill in missing gaps in rustdocs. --- src/attr_quirk.rs | 6 ++--- src/condition.rs | 2 +- src/global.rs | 2 +- src/hyperlink.rs | 2 +- src/lib.rs | 67 +++++++++++++++++++++++++---------------------- src/paint.rs | 52 ++++++++++++++++++++++++++++++++++-- 6 files changed, 92 insertions(+), 39 deletions(-) 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`]. ///