From 8b36683571e078792b20d6f693b817522cf6e992 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Orhun=20Parmaks=C4=B1z?= <orhun@archlinux.org>
Date: Sun, 27 Aug 2023 11:00:35 +0200
Subject: [PATCH] docs(lib): extract feature documentation from Cargo.toml
 (#438)

* docs(lib): extract feature documentation from Cargo.toml

* chore(deps): make `document-features` optional dependency

* docs(lib): document the serde feature from features section
---
 Cargo.toml | 53 ++++++++++++++++++++++++++++++++++++-----------------
 src/lib.rs | 27 +--------------------------
 2 files changed, 37 insertions(+), 43 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 71e288cdf..82e89d9a5 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -22,33 +22,28 @@ rust-version = "1.67.0"
 
 [badges]
 
-[features]
-default = ["crossterm"]
-all-widgets = ["widget-calendar"]
-widget-calendar = ["dep:time"]
-macros = []
-serde = ["dep:serde", "bitflags/serde"]
-
-[package.metadata.docs.rs]
-all-features = true
-# see https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html
-cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
-rustdoc-args = ["--cfg", "docsrs"]
-
 [dependencies]
+#! The crate provides a set of optional features that can be enabled in your `cargo.toml` file.
+#!
+#! Generally an application will only use one backend, so you should only enable one of the following features:
+## enables the [`CrosstermBackend`] backend and adds a dependency on the [Crossterm crate].
+crossterm = { version = "0.27", optional = true }
+## enables the [`TermionBackend`] backend and adds a dependency on the [Termion crate].
+termion = { version = "2.0", optional = true }
+## enables the [`TermwizBackend`] backend and adds a dependency on the [Termwiz crate].
+termwiz = { version = "0.20.0", optional = true }
+
+serde = { version = "1", optional = true, features = ["derive"] }
 bitflags = "2.3"
 cassowary = "0.3"
-crossterm = { version = "0.27", optional = true }
 indoc = "2.0"
 itertools = "0.11"
 paste = "1.0.2"
-serde = { version = "1", optional = true, features = ["derive"] }
 strum = { version = "0.25", features = ["derive"] }
-termion = { version = "2.0", optional = true }
-termwiz = { version = "0.20.0", optional = true }
 time = { version = "0.3.11", optional = true, features = ["local-offset"] }
 unicode-segmentation = "1.10"
 unicode-width = "0.1"
+document-features = { version = "0.2.7", optional = true }
 
 [dev-dependencies]
 anyhow = "1.0.71"
@@ -61,6 +56,30 @@ fakeit = "1.1"
 rand = "0.8"
 pretty_assertions = "1.4.0"
 
+[features]
+default = ["crossterm"]
+#! The following optional features are available for all backends:
+## enables serialization and deserialization of style and color types using the [Serde crate].
+## This is useful if you want to save themes to a file.
+serde = ["dep:serde", "bitflags/serde"]
+
+## enables the [`border!`] macro.
+macros = []
+
+## enables all widgets.
+all-widgets = ["widget-calendar"]
+
+#! Widgets that add dependencies are gated behind feature flags to prevent unused transitive
+#! dependencies. The available features are:
+## enables the [`calendar`] widget module and adds a dependency on the [Time crate].
+widget-calendar = ["dep:time"]
+
+[package.metadata.docs.rs]
+all-features = true
+# see https://doc.rust-lang.org/nightly/rustdoc/scraped-examples.html
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
+rustdoc-args = ["--cfg", "docsrs"]
+
 [[bench]]
 name = "block"
 harness = false
diff --git a/src/lib.rs b/src/lib.rs
index 5a5e65fd4..db4692b71 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -169,31 +169,7 @@
 //! corresponding area.
 //!
 //! # Features
-//!
-//! The crate provides a set of optional features that can be enabled in your `cargo.toml` file.
-//!
-//! Generally an application will only use one backend, so you should only enable one of the
-//! following features:
-//!
-//! - `crossterm` - enables the [`CrosstermBackend`] backend and adds a dependency on the [Crossterm
-//! crate]. Enabled by default.
-//! - `termion` - enables the [`TermionBackend`] backend and adds a dependency on the [Termion
-//!   crate].
-//! - `termwiz` - enables the [`TermwizBackend`] backend and adds a dependency on the [Termwiz
-//!   crate].
-//!
-//! The following optional features are available for all backends:
-//!
-//! - `serde` - enables serialization and deserialization of style and color types using the [Serde
-//! crate]. This is useful if you want to save themes to a file.
-//! - `macros` - enables the [`border!`] macro.
-//! - `all-widgets` - enables all widgets.
-//!
-//! Widgets that add dependencies are gated behind feature flags to prevent unused transitive
-//! dependencies. The available features are:
-//!
-//! - `widget-calendar` - enables the [`calendar`] widget module and adds a dependency on the [Time
-//!   crate].
+#![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
 //!
 //! [`Layout`]: layout::Layout
 //! [`backend`]: backend
@@ -206,7 +182,6 @@
 //! [Termion crate]: https://crates.io/crates/termion
 //! [Termwiz crate]: https://crates.io/crates/termwiz
 //! [Time crate]: https://crates.io/crates/time
-
 // show the feature flags in the generated documentation
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]