feat(manifest): support feature-documentation in manifests

crates/cargo-util-schemas/manifest.schema.json

@@ -649,6 +649,13 @@
           "items": {
             "type": "string"
           }
+        },
+        "doc": {
+          "description": "Documentation for the feature.",
+          "type": [
+            "string",
+            "null"
+          ]
         }
       },
       "required": [

crates/cargo-util-schemas/src/manifest/mod.rs

@@ -1520,6 +1520,9 @@ pub struct FeatureMetadata {
     /// Features that this feature enables.
     pub enables: Vec<String>,
 
+    /// Documentation for the feature.
+    pub doc: Option<String>,
+
     /// This is here to provide a way to see the "unused manifest keys" when deserializing
     #[serde(skip_serializing)]
     #[serde(flatten)]

doc/book/src/reference/unstable.md

@@ -2384,17 +2384,49 @@ The `pubtime` index field  has been stabilized in Rust 1.94.0.
 ## feature-metadata
 
 * Tracking Issue: [#14157](https://github.com/rust-lang/cargo/issues/14157)
+* RFC: [#3416](https://github.com/rust-lang/rfcs/blob/master/text/3416-feature-metadata.md)
 
-This allows to use a table when defining features, with a required `enables` key:
+This allows defining features with a metadata table.
 
 ```toml
+cargo-features = ["feature-metadata"]
+
+[package]
+# ...
+
 [features]
 # same as `foo = []`
 foo = { enables = [] }
 ```
 
-This is equivalent to the array-of-strings syntax.
-Support for other keys should be added later.
+The required `enables` field is equivalent to the array-of-strings syntax.
+
+For other metadata fields, see the subsections below.
+
+### feature-documentation
+
+* Tracking Issue: [#17445](https://github.com/rust-lang/cargo/issues/17445)
+* RFC: [#3485](https://github.com/rust-lang/rfcs/blob/master/text/3485-feature-documentation.md)
+
+This adds a `doc` field to the feature table,
+which provides documentation for the feature.
+
+```toml
+cargo-features = ["feature-metadata"]
+
+[package]
+# ...
+
+[features.serde]
+enables = []
+doc = "Enables support for serialization and deserialization via serde."
+```
+
+The documentation can be consumed and displayed by tools.
+It can be a multi-line TOML string, contain multiple paragraphs, and use Markdown markup,
+similarly to Rust doc comments.
+Tools may only display the first paragraph in some contexts, which should therefore be
+relatively short and make sense without the rest of the description.
 
 ## lockfile-path
 

tests/testsuite/features.rs

@@ -2681,3 +2681,65 @@ c = [
         [("Cargo.toml", normalized_manifest)],
     );
 }
+
+#[cargo_test]
+fn feature_documentation_is_unstable() {
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+                [package]
+                name = "foo"
+                edition = "2015"
+
+                [features]
+                foo = { enables = [], doc = "Enables foo." }
+            "#,
+        )
+        .file("src/main.rs", "fn main() {}")
+        .build();
+
+    p.cargo("check")
+        .with_status(101)
+        .with_stderr_data(str![[r#"
+[ERROR] failed to parse manifest at `[ROOT]/foo/Cargo.toml`
+
+Caused by:
+  feature `feature-metadata` is required
+
+  The package requires the Cargo feature called `feature-metadata`, but that feature is not stabilized in this version of Cargo ([..]).
+  Consider trying a newer version of Cargo (this may require the nightly release).
+  See https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#feature_metadata for more information about the status of this feature.
+
+"#]])
+        .run();
+}
+
+#[cargo_test]
+fn feature_has_documentation() {
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+                cargo-features = ["feature-metadata"]
+
+                [package]
+                name = "foo"
+                edition = "2015"
+
+                [features]
+                foo = { enables = [], doc = "Enables foo." }
+            "#,
+        )
+        .file("src/main.rs", "fn main() {}")
+        .build();
+
+    p.cargo("check")
+        .masquerade_as_nightly_cargo(&["feature-metadata"])
+        .with_stderr_data(str![[r#"
+[CHECKING] foo v0.0.0 ([ROOT]/foo)
+[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
+
+"#]])
+        .run();
+}