From fc8f9779382b7faa7f92bc40d72f8dcbd5849296 Mon Sep 17 00:00:00 2001 From: Josh McKinney Date: Fri, 22 Nov 2024 15:16:55 -0800 Subject: [PATCH] Document feature flags in lib.rs (#947) * Autoformat Cargo.toml Uses VSCode Even Better TOML plugin for opinionated formatting * Document feature flags Use the document-features crate to automatically add documentation about the features to the crate documentation at the crate level. --- Cargo.toml | 89 ++++++++++++++------------------------ src/lib.rs | 2 + src/style.rs | 2 +- src/style/types/colored.rs | 2 +- src/terminal.rs | 2 +- 5 files changed, 37 insertions(+), 60 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 27d6448e..d3b026e7 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -17,91 +17,66 @@ categories = ["command-line-interface", "command-line-utilities"] name = "crossterm" path = "src/lib.rs" -# -# Build documentation with all features -> EventStream is available -# [package.metadata.docs.rs] all-features = true -# -# Features -# [features] -default = ["bracketed-paste", "windows", "events"] -windows = [ - "dep:winapi", - "dep:crossterm_winapi", -] # Disables winapi dependencies from being included into the binary (SHOULD NOT be disabled on windows). -bracketed-paste = [ -] # Enables triggering a `Event::Paste` when pasting text into the terminal. -event-stream = ["dep:futures-core", "events"] # Enables async events -use-dev-tty = [ - "filedescriptor", - "rustix/process", -] # Enables raw file descriptor polling / selecting instead of mio. -events = [ - "dep:mio", - "dep:signal-hook", - "dep:signal-hook-mio", -] # Enables reading input/events from the system. -serde = ["dep:serde", "bitflags/serde"] # Enables 'serde' for various types. - -# -# Shared dependencies -# +default = ["bracketed-paste", "events", "windows"] + +#! ### Default features +## Enables triggering [`Event::Paste`](event::Event::Paste) when pasting text into the terminal. +bracketed-paste = [] + +## Enables reading input/events from the system using the [`event`] module. +events = ["dep:mio", "dep:signal-hook", "dep:signal-hook-mio"] + +## Enables windows specific crates. +windows = ["dep:winapi", "dep:crossterm_winapi"] + +#! ### Optional Features + +## Enables the [EventStream](event::EventStream) struct for async event reading. +event-stream = ["dep:futures-core", "events"] + +## Enables [`serde`] for various types. +serde = ["dep:serde", "bitflags/serde"] + +## Enables raw file descriptor polling / selecting instead of mio. +use-dev-tty = ["filedescriptor", "rustix/process"] + [dependencies] bitflags = { version = "2.3" } -parking_lot = "0.12" - -# optional deps only added when requested +document-features = "0.2.10" futures-core = { version = "0.3", optional = true, default-features = false } +parking_lot = "0.12" serde = { version = "1.0", features = ["derive"], optional = true } -# # Windows dependencies -# -[target.'cfg(windows)'.dependencies.winapi] -version = "0.3.9" -features = ["winuser", "winerror"] -optional = true - [target.'cfg(windows)'.dependencies] crossterm_winapi = { version = "0.9.1", optional = true } +winapi = { version = "0.3.9", optional = true, features = ["winuser", "winerror"] } -# # UNIX dependencies -# [target.'cfg(unix)'.dependencies] +filedescriptor = { version = "0.8", optional = true } # Default to using rustix for UNIX systems, but provide an option to use libc for backwards # compatibility. libc = { version = "0.2", default-features = false, optional = true } -rustix = { version = "0.38.34", default-features = false, features = [ - "std", - "stdio", - "termios", -] } -signal-hook = { version = "0.3.17", optional = true } -filedescriptor = { version = "0.8", optional = true } mio = { version = "1.0", features = ["os-poll"], optional = true } -signal-hook-mio = { version = "0.2.4", features = [ - "support-v1_0", -], optional = true } +rustix = { version = "0.38.34", default-features = false, features = ["std", "stdio", "termios"] } +signal-hook = { version = "0.3.17", optional = true } +signal-hook-mio = { version = "0.2.4", features = ["support-v1_0"], optional = true } -# -# Dev dependencies (examples, ...) -# [dev-dependencies] -tokio = { version = "1.25", features = ["full"] } +async-std = "1.12" futures = "0.3" futures-timer = "3.0" -async-std = "1.12" serde_json = "1.0" serial_test = "2.0.0" temp-env = "0.3.6" +tokio = { version = "1.25", features = ["full"] } -# # Examples -# [[example]] name = "event-read" required-features = ["bracketed-paste", "events"] diff --git a/src/lib.rs b/src/lib.rs index 453382a7..41e235b2 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -223,6 +223,8 @@ //! Ok(()) //! } //!``` +//! ## Feature Flags +#![doc = document_features::document_features!()] //! //! [write]: https://doc.rust-lang.org/std/io/trait.Write.html //! [stdout]: https://doc.rust-lang.org/std/io/fn.stdout.html diff --git a/src/style.rs b/src/style.rs index b67a421b..034b54ad 100644 --- a/src/style.rs +++ b/src/style.rs @@ -184,7 +184,7 @@ pub fn available_color_count() -> u16 { /// /// # Notes /// -/// crossterm supports NO_COLOR (https://no-color.org/) to disabled colored output. +/// crossterm supports NO_COLOR () to disabled colored output. /// /// This API allows applications to override that behavior and force colorized output /// even if NO_COLOR is set. diff --git a/src/style/types/colored.rs b/src/style/types/colored.rs index c9feecdb..47f35666 100644 --- a/src/style/types/colored.rs +++ b/src/style/types/colored.rs @@ -71,7 +71,7 @@ impl Colored { } /// Checks whether ansi color sequences are disabled by setting of NO_COLOR - /// in environment as per https://no-color.org/ + /// in environment as per pub fn ansi_color_disabled() -> bool { !std::env::var("NO_COLOR") .unwrap_or("".to_string()) diff --git a/src/terminal.rs b/src/terminal.rs index e7406bed..3aebc1f8 100644 --- a/src/terminal.rs +++ b/src/terminal.rs @@ -148,7 +148,7 @@ pub struct WindowSize { /// Returns the terminal size `[WindowSize]`. /// /// The width and height in pixels may not be reliably implemented or default to 0. -/// For unix, https://man7.org/linux/man-pages/man4/tty_ioctl.4.html documents them as "unused". +/// For unix, documents them as "unused". /// For windows it is not implemented. pub fn window_size() -> io::Result { sys::window_size()