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

cargo-features.md

@@ -142,19 +142,7 @@ Documented in [its documentation](https://docs.rs/git-packetline).
 
 ### git-transport
 
-The _client_ portion of transport can be blocking or async. If none is selected, it will be missing entirely.
-
-- _mutually exclusive_
-    - Specifying both causes a compile error, preventing the use of `--all-features`.
-    - **blocking-client**
-      - If set, blocking implementations of the typical git transports become available in `crate::client`
-      - **http-client-curl**
-          - Adds support for the http and https transports using the Rust bindings for `libcurl`
-  - **async-client**
-      - If set, an async implementations of the git transports becomes available in `crate::client`.
-      - Suitable for implementing your own transports while using git's way of communication, typically in conjunction with a custom server.
-         - **Note** that the _blocking_ client has a wide range of available transports, with the _async_ version of it supporting only the TCP based `git` transport leaving you
-            with the responsibility to providing such an implementation of `futures-io::AsyncRead/AsyncWrite` yourself.
+Documented in [its documentation](https://docs.rs/git-transport).
 
 ### git-protocol
 

git-transport/Cargo.toml

@@ -13,12 +13,25 @@ doctest = false
 
 [features]
 default = []
-## Data structures implement `serde::Serialize` and `serde::Deserialize`.
-serde1 = ["serde"]
-http-client-curl = ["curl", "base64", "git-features/io-pipe", "blocking-client"]
+
+#! ### _Mutually Exclusive Client_
+#! The _client_ portion of transport can be blocking or async. If none is selected, it will be missing entirely.
+#! Specifying both causes a compile error, preventing the use of `--all-features`.
+
+## If set, blocking implementations of the typical git transports become available in `crate::client`
 blocking-client = ["git-packetline/blocking-io"]
+## Implies `blocking-client`, and adds support for the http and https transports using the Rust bindings for `libcurl`.
+http-client-curl = ["curl", "base64", "git-features/io-pipe", "blocking-client"]
+## If set, an async implementations of the git transports becomes available in `crate::client`.
+## Suitable for implementing your own transports while using git's way of communication, typically in conjunction with a custom server.
+## **Note** that the _blocking_ client has a wide range of available transports, with the _async_ version of it supporting only the TCP based `git` transport leaving you
+## with the responsibility to providing such an implementation of `futures-io::AsyncRead/AsyncWrite` yourself.
 async-client = ["git-packetline/async-io", "async-trait", "futures-lite", "futures-io", "pin-project-lite"]
 
+#! ### Other
+## Data structures implement `serde::Serialize` and `serde::Deserialize`.
+serde1 = ["serde"]
+
 [[test]]
 name = "blocking-transport"
 path = "tests/blocking-transport.rs"
@@ -57,6 +70,8 @@ curl = { version = "0.4", optional = true, features = ["static-curl", "static-ss
 thiserror = "1.0.26"
 base64 = { version = "0.13.0", optional = true }
 
+document-features = { version = "0.1.0", optional = true }
+
 [dev-dependencies]
 git-pack = { path = "../git-pack" }
 git-hash = { path = "../git-hash" }
@@ -65,4 +80,4 @@ maybe-async = "0.2.6"
 blocking = "1.0.2"
 
 [package.metadata.docs.rs]
-features = ["http-client-curl"]
+features = ["http-client-curl", "document-features"]

git-transport/src/lib.rs

@@ -2,6 +2,11 @@
 //! [`connect()`] to establish a connection given a repository URL.
 //!
 //! All git transports are supported, including `ssh`, `git`, `http` and `https`, as well as local repository paths.
+//! ## Feature Flags
+#![cfg_attr(
+    feature = "document-features",
+    cfg_attr(doc, doc = ::document_features::document_features!())
+)]
 #![forbid(unsafe_code)]
 #![deny(rust_2018_idioms, missing_docs)]