feat: in-manifest and in-bin documentation of feature toggles (#329)

Unfortunately, these don't show up on docs.rs due to it being a abinary
only crate. One could consider throwing in a lib just for good measure.

Cargo.toml

@@ -27,32 +27,52 @@ doctest = false
 [features]
 default = ["max"]
 
-max = ["fast", "pretty-cli", "http-client-curl", "gitoxide-core-tools", "gitoxide-core-blocking-client",
-       "prodash-render-line", "prodash-render-tui",
-       "prodash/render-line-autoconfigure" ]
+## Makes the crate execute as fast as possible by supporting parallel computation of otherwise long-running functions
+## as well as fast, hardware accelerated hashing, along with a faster zlib backend.
+## If disabled, the binary will be visibly smaller.
+fast = ["git-features/parallel", "git-features/fast-sha1", "git-features/zlib-ng-compat"]
+
+## Use `clap` 3.0 to build the prettiest, best documented and most user-friendly CLI at the expense of binary size.
+## Provides a terminal user interface for detailed and exhaustive progress.
+## Provides a line renderer for leaner progress display, without the need for a full-blown TUI.
+pretty-cli = [ "gitoxide-core/serde1", "prodash/progress-tree", "prodash/progress-tree-log", "prodash/local-time", "gitoxide-core/local-time-support", "env_logger" ]
+
+## The `--verbose` flag will be powered by an interactive progress mechanism that doubles as log as well as interactive progress
+## that appears after a short duration.
+prodash-render-line-crossterm = ["prodash-render-line", "prodash/render-line-crossterm", "atty", "crosstermion"]
+
 
-lean = ["fast", "pretty-cli", "http-client-curl", "gitoxide-core-tools", "gitoxide-core-blocking-client",
-        "prodash-render-line" ]
-lean-async = ["fast", "pretty-cli", "gitoxide-core-tools", "gitoxide-core-async-client",
-              "prodash-render-line"]
+#! ### Convenience Features
+#! These combine common choices of the above features to represent typical builds
 
+## *fast* + *prodash-render-tui-crossterm* + *prodash-render-line-crossterm* + *http* + *gitoxide-core-tools* + *client-networking*
+max = ["fast", "pretty-cli", "http-client-curl", "gitoxide-core-tools", "gitoxide-core-blocking-client", "prodash-render-line", "prodash-render-tui", "prodash/render-line-autoconfigure" ]
+
+## *fast* + *prodash-render-line-crossterm* + *gitoxide-core-tools* + *client-networking*.
+lean = ["fast", "pretty-cli", "http-client-curl", "gitoxide-core-tools", "gitoxide-core-blocking-client", "prodash-render-line" ]
+## fast* + *prodash-render-line-crossterm* + *gitoxide-core-tools* + *client-async-networking*.
+## Due to async client-networking not being implemented for most transports, this one supports only the 'git' transport.
+## It uses, however, a fully asynchronous networking implementation which can serve a real-world example on how to implement custom async transports.
+lean-async = ["fast", "pretty-cli", "gitoxide-core-tools", "gitoxide-core-async-client", "prodash-render-line"]
+
+## As small as it can possibly be, no threading, no fast sha1, log based progress only, rust based zlib implementation.
+## no networking, local operations only.
 small = ["pretty-cli", "git-features/rustsha1", "git-features/zlib-rust-backend", "prodash/progress-log", "atty"]
 
+#! ### `gitoxide-core` Configuration
+
+##  A way to enable all `gitoxide-core` tools found in `gix tools`
 gitoxide-core-tools = ["gitoxide-core/organize", "gitoxide-core/estimate-hours"]
-gitoxide-core-blocking-client = ["gitoxide-core/blocking-client"]
-gitoxide-core-async-client = ["gitoxide-core/async-client", "futures-lite"]
-http-client-curl = ["git-transport-for-configuration-only/http-client-curl"]
-fast = ["git-features/parallel", "git-features/fast-sha1", "git-features/zlib-ng-compat"]
 
-pretty-cli = [
-    "gitoxide-core/serde1",
-    "prodash/progress-tree",
-    "prodash/progress-tree-log",
-    "prodash/local-time",
-    "gitoxide-core/local-time-support",
-    "env_logger" ]
+#! #### Mutually Exclusive Networking
+#! If both are set a compile error is triggered. This also means that `cargo … --all-features` will fail.
 
-prodash-render-line-crossterm = ["prodash-render-line", "prodash/render-line-crossterm", "atty", "crosstermion"]
+## Use blocking client networking.
+gitoxide-core-blocking-client = ["gitoxide-core/blocking-client"]
+## Support synchronous 'http' and 'https' transports (e.g. for clone, fetch and push) at the expense of compile times and binary size.
+http-client-curl = ["git-transport-for-configuration-only/http-client-curl"]
+## Use async client networking.
+gitoxide-core-async-client = ["gitoxide-core/async-client", "futures-lite"]
 
 # internal
 prodash-render-tui = ["prodash/render-tui", "prodash/render-tui-crossterm", "prodash/progress-tree", "futures-lite"]
@@ -75,6 +95,8 @@ env_logger = { version = "0.9.0", optional = true, default-features = false, fea
 crosstermion = { version = "0.9.0", optional = true, default-features = false }
 futures-lite = { version = "1.12.0", optional = true, default-features = false, features = ["std"] }
 
+document-features = { version = "0.1.0", optional = true }
+
 [profile.dev.package]
 git-object = { opt-level = 3 }
 git-ref = { opt-level = 3 }
@@ -140,3 +162,6 @@ members = [
 exclude = ["cargo-smart-release/tests/fixtures/tri-depth-workspace/a",
            "cargo-smart-release/tests/fixtures/tri-depth-workspace/b",
            "cargo-smart-release/tests/fixtures/tri-depth-workspace/c"]
+
+[package.metadata.docs.rs]
+features = ["document-features", "max"]

cargo-features.md

@@ -6,47 +6,7 @@ This guide documents which features are available for each of the crates provide
 
 ### gitoxide
 
-The top-level command-line interface.
-
-* **fast**
-    * Makes the crate execute as fast as possible by supporting parallel computation of otherwise long-running functions
-      as well as fast, hardware accelerated hashing, along with a faster zlib backend.
-    * If disabled, the binary will be visibly smaller.
-* **http**
-    * support synchronous 'http' and 'https' transports (e.g. for clone, fetch and push) at the expense of compile times and binary size
-* _(mutually exclusive)_
-    * **pretty-cli**
-        * Use `clap` 3.0 to build the prettiest, best documented and most user-friendly CLI at the expense of binary size.
-        * provides a terminal user interface for detailed and exhaustive progress.
-        * provides a line renderer for leaner progress
-    * **lean-cli**
-        * Use `argh` to produce a usable binary with decent documentation that is smallest in size, usually 300kb less than `pretty-cli`.
-        * If `pretty-cli` is enabled as well, `lean-cli` will take precedence, and you pay for building unnecessary dependencies.
-        * provides a line renderer for lean but pretty progress
-* **prodash-render-line-crossterm** 
-    * The `--verbose` flag will be powered by an interactive progress mechanism that doubles as log as well as interactive progress
-      that appears after a short duration.
-* **gitoxide-core-tools**
-    * A way to enable all `gitoxide-core` tools found in `gix tools`
-* _mutually exclusive_    
-    * If both are set a compile error is triggered. This also means that `cargo … --all-features` will fail.
-    * **gitoxide-core-blocking-client**
-        * Use blocking client networking.
-    * **gitoxide-core-async-client**
-      * Use async client networking.
-
-There are **convenience features**, which combine common choices of the above into one name
-
-* **max** = *fast* + *prodash-render-tui-crossterm* + *prodash-render-line-crossterm* + *http* + *gitoxide-core-tools* + *client-networking*
-    * _default_, for unix and windows
-* **lean** = *fast* + *prodash-render-line-crossterm* + *gitoxide-core-tools* + *client-networking*
-    * cross-platform by nature as this comes with simplified log based progress
-* **lean-async** = *fast* + *prodash-render-line-crossterm* + *gitoxide-core-tools* + *client-async-networking*
-   * Due to async client-networking not being implemented for most transports, this one supports only the 'git' transport. It uses, however, a fully asynchronous
-     networking implementation which can serve a real-world example on how to implement custom async transports.
-* **small**
-    * As small as it can possibly be, no threading, no fast sha1, log based progress only, rust based zlib implementation.
-    * no networking, local operations only.
+Documented in [its documentation](https://docs.rs/gitoxide-core).
 
 ### gitoxide-core
 

src/plumbing-cli.rs

@@ -1,3 +1,8 @@
+//! ## Feature Flags
+#![cfg_attr(
+    feature = "document-features",
+    cfg_attr(doc, doc = ::document_features::document_features!())
+)]
 #![forbid(unsafe_code)]
 #![deny(rust_2018_idioms)]
 

src/porcelain-cli.rs

@@ -1,3 +1,8 @@
+//! ## Feature Flags
+#![cfg_attr(
+    feature = "document-features",
+    cfg_attr(doc, doc = ::document_features::document_features!())
+)]
 #![forbid(unsafe_code)]
 #![deny(rust_2018_idioms)]