feat(manifest): support `feature-documentation` in manifests by AudaciousAxiom · Pull Request #17447 · rust-lang/cargo

AudaciousAxiom · 2026-09-06T09:53:17Z

What does this PR try to resolve?

This implements part of RFC feature-documentation, tracked by #17445. This only adds support for the new key in the schema. This doesn't add anything to the index as this was decided against.

This doesn't not introduce a dedicated unstable feature, as mentioned in #17445 (comment), and the new key is simply gated behind the existing feature-metadata unstable feature.

The exact name of the key is still TBD, but it will be easy to rename either in this PR or later.

Open questions

How to prepare the documentation for this? Not introducing an unstable feature means there is no dedicated place for that in the book, should it be added to the existing docs of feature-metadata there, or stacked as a separate PR on top of docs(book): document the table syntax of features #17446?

Future work

At least the following is still to be done for this RFC (I may not have time to tackle this):

Exposing the new key through cargo metadata.
Exposing the documentation to humans through cargo add (and through other tools/services, like docs.rs).

How to test and review this PR?

The tests should be enough to review this.

AudaciousAxiom · 2026-09-06T09:54:00Z

+
+    p.cargo("check")
+        .masquerade_as_nightly_cargo(&["feature-metadata"])
+        .run();


Should there be a check of the new key being parsed?

View changes since the review

I guess this can similarily be split into two (test, fix) commits, so that we don't need a verification but the test diff showing that it was an unused manifest key.

If we had a cargo metadata integration, then we'll have a verification for the consumption side (yeah we should continue the design discussion).

Or we can also add cargo-info integration for feature metadata in a follow-up as part of the verification. @0xPoe any opinion on this? I am not sure whether it should be behind a unstable flag though, given cargo-info is purely for human not programmable.

I guess this can similarily be split into two (test, fix) commits, so that we don't need a verification but the test diff showing that it was an unused manifest key.

I've split the PR: the feature_has_documentation test case is now introduced in the first commit, triggers the "unused key" warning, which then disappears in the second commit as support for the key is added.

Or we can also add cargo-info integration for feature metadata in a follow-up as part of the verification. @0xPoe any opinion on this? I am not sure whether it should be behind a unstable flag though, given cargo-info is purely for human not programmable.

Sounds interesting. I believe docs may also be helpful for human use. However, the biggest challenge would be the UI design. In the current cargo-info output, it is difficult to display the documents directly within the existing layout.

AudaciousAxiom · 2026-09-06T09:56:17Z

+                edition = "2015"
+
+                [features]
+                foo = { enables = [], doc = "Enables foo." }


I think it's still a bit unclear what the style of these should be: should these be capitalized and terminated with a period? I suppose this also depends on whether cargo add (and others) apply any transformation to these.

View changes since the review

IMHO it should follow what rustdoc suggesting: https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html. Strip trailing periods sounds a future problem and also is human-eye-pleasing so we can change whenever needed.

AudaciousAxiom · 2026-09-06T10:14:52Z

The CI failure seems unrelated.

rustbot · 2026-09-06T10:14:58Z

r? @weihanglo

rustbot has assigned @weihanglo.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

Owners of files modified in this PR: @epage, @weihanglo
@epage, @weihanglo expanded to epage, weihanglo
Random selection from epage, weihanglo

weihanglo

Thanks!

Could you expand https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#feature-metadata a bit? Perhaps with a subsection linking to feature-documentation RFC and tracking issue.
(Also just noticed that we forgot to put feature-metadata RFC link there)

View changes since this review

weihanglo · 2026-09-06T12:09:38Z

    /// Features that this feature enables.
    pub enables: Vec<String>,

+    /// Unstable feature `feature-documentation`. Documentation for the feature.


Suggested change

/// Unstable feature `feature-documentation`. Documentation for the feature.

/// Documentation for the feature.

I think this should be sufficient?

weihanglo · 2026-09-06T12:13:40Z

+
+    p.cargo("check")
+        .masquerade_as_nightly_cargo(&["feature-metadata"])
+        .run();


I guess this can similarily be split into two (test, fix) commits, so that we don't need a verification but the test diff showing that it was an unused manifest key.

weihanglo · 2026-09-06T12:14:45Z

+
+    p.cargo("check")
+        .masquerade_as_nightly_cargo(&["feature-metadata"])
+        .run();


If we had a cargo metadata integration, then we'll have a verification for the consumption side (yeah we should continue the design discussion).

Or we can also add cargo-info integration for feature metadata in a follow-up as part of the verification. @0xPoe any opinion on this? I am not sure whether it should be behind a unstable flag though, given cargo-info is purely for human not programmable.

weihanglo · 2026-09-06T12:21:23Z

+                edition = "2015"
+
+                [features]
+                foo = { enables = [], doc = "Enables foo." }


IMHO it should follow what rustdoc suggesting: https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html. Strip trailing periods sounds a future problem and also is human-eye-pleasing so we can change whenever needed.

AudaciousAxiom · 2026-09-06T13:29:35Z

 This is equivalent to the array-of-strings syntax.
 Support for other keys should be added later.

+### feature-documentation


Could you expand https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#feature-metadata a bit? Perhaps with a subsection linking to feature-documentation RFC and tracking issue.

I've added a subsection. It's not added to the ToC at the beginning of the page as feature-documentation is not actually an unstable feature.

View changes since the review

AudaciousAxiom · 2026-09-06T13:30:31Z

+```toml
+[features.serde]
+enables = []
+doc = "Enables support for serialization and deserialization via serde."


This is mostly the example from the RFC, but I've taken the liberty to make it fit the rustdoc guidelines a bit more.

View changes since the review

rustbot added the A-manifest Area: Cargo.toml issues label Sep 6, 2026

AudaciousAxiom commented Sep 6, 2026

View reviewed changes

AudaciousAxiom force-pushed the feat/rfc-impl-feature-documentation-schema branch from e5b1573 to 0baabe5 Compare September 6, 2026 09:59

AudaciousAxiom marked this pull request as ready for review September 6, 2026 10:14

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Sep 6, 2026

rustbot assigned weihanglo Sep 6, 2026

weihanglo reviewed Sep 6, 2026

View reviewed changes

test(manifest): test the yet-unsupported feature documentation key

fae8363

AudaciousAxiom force-pushed the feat/rfc-impl-feature-documentation-schema branch from 0baabe5 to 5d1f882 Compare September 6, 2026 13:22

rustbot added the A-documenting-cargo-itself Area: Cargo's documentation label Sep 6, 2026

feat(manifest): support feature-documentation in manifests

9199a6e

AudaciousAxiom force-pushed the feat/rfc-impl-feature-documentation-schema branch from 5d1f882 to 9199a6e Compare September 6, 2026 13:23

AudaciousAxiom commented Sep 6, 2026

View reviewed changes

	/// Unstable feature `feature-documentation`. Documentation for the feature.
	/// Documentation for the feature.

Uh oh!

Uh oh!

Conversation

AudaciousAxiom commented Sep 6, 2026

What does this PR try to resolve?

Open questions

Future work

How to test and review this PR?

Uh oh!

AudaciousAxiom Sep 6, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AudaciousAxiom Sep 6, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AudaciousAxiom commented Sep 6, 2026

Uh oh!

rustbot commented Sep 6, 2026

Uh oh!

weihanglo left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AudaciousAxiom Sep 6, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AudaciousAxiom Sep 6, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

AudaciousAxiom Sep 6, 2026 •

edited by rustbot

Loading

AudaciousAxiom Sep 6, 2026 •

edited by rustbot

Loading

weihanglo left a comment •

edited by rustbot

Loading

AudaciousAxiom Sep 6, 2026 •

edited by rustbot

Loading

AudaciousAxiom Sep 6, 2026 •

edited by rustbot

Loading