Merge #639

639: Change documentation of feature flags r=jonasbb a=jonasbb

Document the feature flags in the Cargo.toml file instead of a separate
file. Keep the old file, but generate the content from the Cargo.toml
using the `document-features` crate.

The benefit of this approach is that the documentation is stored next to
the features. lib.rs has a new feature that reads the documentation from
there and shows it as part of the feature list.

bors r+

Co-authored-by: Jonas Bushart <[email protected]>

serde_with/Cargo.toml

@@ -24,49 +24,98 @@ include = ["src/**/*", "tests/**/*", "LICENSE-*", "README.md", "CHANGELOG.md"]
 maintenance = {status = "actively-developed"}
 
 # When adding new features update the documentation in feature-flags.md
+# The features are documented using https://docs.rs/document-features
+# lib.rs has support for generating the documentation from the feature flags.
+#   https://users.rust-lang.org/t/new-features-on-lib-rs/98560
 [features]
 default = ["std", "macros"]
 
-alloc = [
-    "serde/alloc",
+#! `serde_with` is fully `no_std` compatible, by depending on it with `default-features = false`.
+#! Support for `alloc` and `std` can be enabled with the respective features.
+#! Some features require `alloc` or `std` support and might not work in a `no_std` environment.
 
-    "base64?/alloc",
-    "chrono_0_4?/alloc",
-    "hex?/alloc",
-    "serde_json?/alloc",
-    "time_0_3?/alloc",
-]
-std = [
-    "alloc",
-    "serde/std",
-
-    # Enables `Local` type
-    "chrono_0_4?/clock",
-    "chrono_0_4?/std",
-    "indexmap_1?/std",
-    "indexmap_2?/std",
-    "time_0_3?/serde-well-known",
-    "time_0_3?/std",
-]
+## Enable support for types from the `alloc` crate when running in a `no_std` environment.
+alloc = ["serde/alloc", "base64?/alloc", "chrono_0_4?/alloc", "hex?/alloc", "serde_json?/alloc", "time_0_3?/alloc"]
+## Enables support for various types from the std library.
+## This will enable `std` support in all dependencies too.
+## The feature enabled by default and also enables `alloc`.
+std = ["alloc", "serde/std", "chrono_0_4?/clock", "chrono_0_4?/std", "indexmap_1?/std", "indexmap_2?/std", "time_0_3?/serde-well-known", "time_0_3?/std"]
+
+#! # Documentation
+#!
+#! The following features enhance the documentation of `serde_with`.
+
+## The `guide` feature enables inclusion of this user guide.
+## The feature only changes the rustdoc output and enables no other effects.
+guide = ["dep:doc-comment", "dep:document-features", "macros", "std"]
 
+#! # Features
+#!
+#! The following features enable support for types from other crates or enable additional functionality, that requires further dependencies to be pulled in.
+#! These features are disabled by default to miniminze the amount of required dependencies.
+
+## The feature enables serializing data in base64 format.
 base64 = ["dep:base64", "alloc"]
+## Deprecated feature name. Use `chrono_0_4` instead.
 chrono = ["chrono_0_4"]
+## The feature enables integration of `chrono` v0.4 specific conversions.
+## This includes support for the timestamp and duration types.
+## More features are available in combination with `alloc` or `std`.
+## The legacy feature name `chrono` is still available for v1 compatability.
+##
+## This pulls in `chrono` v0.4 as a dependency.
 chrono_0_4 = ["dep:chrono_0_4"]
-guide = ["dep:doc-comment", "macros", "std"]
-hex = ["dep:hex", "alloc"]
+## The feature enables `hashbown::{HashMap, HashSet}` as supported containers.
+##
+## This pulls in `hashbrown` v0.14 as a dependency.
+## It enables the `alloc` feature.
+## Some functionality is only available when `std` is enabled too.
 hashbrown_0_14 = ["dep:hashbrown_0_14", "alloc"]
+## The feature enables serializing data in hex format.
+##
+## This pulls in `hex` as a dependency.
+## It enables the `alloc` feature.
+hex = ["dep:hex", "alloc"]
+## Deprecated feature name. Use `indexmap_1` instead.
 indexmap = ["indexmap_1"]
+## The feature enables implementations of `indexmap` v1 specific checks.
+## This includes support for checking duplicate keys and duplicate values.
+## The legacy feature name `indexmap` is still available for v1 compatability.
+##
+## This pulls in `indexmap` v1 as a dependency.
+## It enables the `alloc` feature.
+## Some functionality is only available when `std` is enabled too.
 indexmap_1 = ["dep:indexmap_1", "alloc"]
+## The feature enables implementations of `indexmap` v2 specific checks.
+## This includes support for checking duplicate keys and duplicate values.
+##
+## This pulls in `indexmap` v2 as a dependency.
+## It enables the `alloc` feature.
+## Some functionality is only available when `std` is enabled too.
 indexmap_2 = ["dep:indexmap_2", "alloc"]
+## The feature enables JSON conversions from the `json` module.
+##
+## This pulls in `serde_json` as a dependency.
+## It enables the `alloc` feature.
 json = ["dep:serde_json", "alloc"]
+## The feature enables all helper macros and derives.
+## It is enabled by default, since the macros provide a usability benefit, especially for `serde_as`.
+##
+## This pulls in `serde_with_macros` as a dependency.
 macros = ["dep:serde_with_macros"]
+## The feature enables integration of `time` v0.3 specific conversions.
+## This includes support for the timestamp and duration types.
+##
+## This pulls in `time` v0.3 as a dependency.
+## Some functionality is only available when `alloc` or `std` is enabled too.
 time_0_3 = ["dep:time_0_3"]
 
 # When adding new optional dependencies update the documentation in feature-flags.md
 [dependencies]
 base64 = {version = "0.21.0", optional = true, default-features = false}
 chrono_0_4 = {package = "chrono", version = "0.4.20", optional = true, default-features = false, features = ["serde"]}
 doc-comment = {version = "0.3.3", optional = true}
+document-features = {version = "0.2.7", optional = true}
 hashbrown_0_14 = {package = "hashbrown", version = "0.14.0", optional = true, default-features = false, features = ["serde"]}
 hex = {version = "0.4.3", optional = true, default-features = false}
 indexmap_1 = {package = "indexmap", version = "1.8", optional = true, default-features = false, features = ["serde-1"]}

serde_with/src/guide/feature_flags.rs

@@ -0,0 +1,3 @@
+//! # Available Feature Flags
+//!
+#![doc = document_features::document_features!()]

serde_with/src/lib.rs

@@ -375,7 +375,7 @@ macro_rules! generate_guide {
 #[cfg(feature = "guide")]
 generate_guide! {
     pub mod guide {
-        pub mod feature_flags;
+        @code pub mod feature_flags;
         pub mod serde_as;
         pub mod serde_as_transformations;
     }