diff --git a/Cargo.lock b/Cargo.lock index bf4b3e82..77470651 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -214,6 +214,15 @@ version = "0.3.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "fea41bba32d969b513997752735605054bc0dfa92b4c56bf1189f2e174be7a10" +[[package]] +name = "document-features" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e493c573fce17f00dcab13b6ac057994f3ce17d1af4dc39bfd482b83c6eb6157" +dependencies = [ + "litrs", +] + [[package]] name = "equivalent" version = "1.0.1" @@ -364,6 +373,12 @@ dependencies = [ "cc", ] +[[package]] +name = "litrs" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f9275e0933cf8bb20f008924c0cb07a0692fe54d8064996520bf998de9eb79aa" + [[package]] name = "log" version = "0.4.17" @@ -607,6 +622,7 @@ dependencies = [ "base64 0.21.0", "chrono", "doc-comment", + "document-features", "expect-test", "fnv", "glob", diff --git a/serde_with/Cargo.toml b/serde_with/Cargo.toml index 6b2df0f4..6ec23cdb 100644 --- a/serde_with/Cargo.toml +++ b/serde_with/Cargo.toml @@ -24,42 +24,90 @@ 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 @@ -67,6 +115,7 @@ time_0_3 = ["dep:time_0_3"] 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"]} diff --git a/serde_with/src/guide/feature_flags.md b/serde_with/src/guide/feature_flags.md deleted file mode 100644 index 201625d1..00000000 --- a/serde_with/src/guide/feature_flags.md +++ /dev/null @@ -1,107 +0,0 @@ -# Available Feature Flags - -This crate has the following features which can be enabled. -Each entry will explain the feature in more detail. - -`serde_with` is fully `no_std` compatible. -Using it in a `no_std` environment requires using `default-features = false`, since `std` is enabled by default. - -1. [`alloc`](#alloc) -2. [`std` (default)](#std-default) -3. [`base64`](#base64) -4. [`chrono_0_4`](#chrono_0_4) -5. [`guide`](#guide) -6. [`hashbrown_0_14`](#hashbrown_0_14) -7. [`hex`](#hex) -8. [`indexmap_1`](#indexmap_1) -9. [`indexmap_2`](#indexmap_2) -10. [`json`](#json) -11. [`macros` (default)](#macros-default) -12. [`time_0_3`](#time_0_3) - -## `alloc` - -Enable support for types from the `alloc` crate when running in a `no_std` environment. - -## `std` (default) - -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`. - -## `base64` - -The `base64` feature enables serializing data in base64 format. - -This pulls in `base64` as a dependency. -It enables the `alloc` feature. - -## `chrono_0_4` - -The `chrono_0_4` feature enables integration of `chrono_0_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. - -## `guide` - -The `guide` feature enables inclusion of this user guide. -The feature only changes the rustdoc output and enables no other effects. - -## `hashbrown_0_14` - -The `hashbrown_0_14` 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. - -## `hex` - -The `hex` feature enables serializing data in hex format. - -This pulls in `hex` as a dependency. -It enables the `alloc` feature. - -## `indexmap_1` - -The `indexmap_1` 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_2` - -The `indexmap_2` 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. - -## `json` - -The `json` features enables JSON conversions from the `json` module. - -This pulls in `serde_json` as a dependency. -It enables the `alloc` feature. - -## `macros` (default) - -The `macros` features 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. - -## `time_0_3` - -The `time_0_3` 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. diff --git a/serde_with/src/guide/feature_flags.rs b/serde_with/src/guide/feature_flags.rs new file mode 100644 index 00000000..07ca2673 --- /dev/null +++ b/serde_with/src/guide/feature_flags.rs @@ -0,0 +1,3 @@ +//! # Available Feature Flags +//! +#![doc = document_features::document_features!()] diff --git a/serde_with/src/lib.rs b/serde_with/src/lib.rs index 8a51068e..8b8c2643 100644 --- a/serde_with/src/lib.rs +++ b/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; }