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.

Author: joshka

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"]

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

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 (<https://no-color.org/>) to disabled colored output.
 ///
 /// This API allows applications to override that behavior and force colorized output
 /// even if NO_COLOR is set.

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 <https://no-color.org/>
     pub fn ansi_color_disabled() -> bool {
         !std::env::var("NO_COLOR")
             .unwrap_or("".to_string())

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, <https://man7.org/linux/man-pages/man4/tty_ioctl.4.html> documents them as "unused".
 /// For windows it is not implemented.
 pub fn window_size() -> io::Result<WindowSize> {
     sys::window_size()