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-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

Looks good to me. Let me know if you want to address #17447 (comment) or I can tweak a bit for you :)

View changes since this review

Update cargo submodule 6 commits in 7941be6fb416b4cd9666aef7b858dfea25587a8c..30754e087c97c58c6c36d0440d4cf1aecb3330a9 2026-09-11 20:47:37 +0000 to 2026-09-15 18:19:50 +0000 - fix(git): For git cli, tell users what config we aren't forwarding on error (rust-lang/cargo#17477) - Lower the lint level of `manual_readme` and `non_kebab_case_bins` to `allow` (rust-lang/cargo#17478) - fix(trim-paths)!: unremap file in one JSON doc (rust-lang/cargo#17476) - feat(manifest): support `feature-documentation` in manifests (rust-lang/cargo#17447) - chore: Add Muscraft to the review rotation (rust-lang/cargo#17471) - Specify `--edition` in `messages` tests (rust-lang/cargo#17470) r? Urgau for the debugger script part --- 🤖 LLM disclosure: I probably should have tested this change manually, though I let LLM verify it working, sorry. Will do a manual test when I have time or if somebody beats me on that.

Update cargo submodule 9 commits in 7941be6fb416b4cd9666aef7b858dfea25587a8c..495c385d0875c4ba51eb72ea0448a2d4c018b8d4 2026-09-11 20:47:37 +0000 to 2026-09-16 12:48:58 +0000 - Report the number of errors with `build.warnings='deny'` (rust-lang/cargo#17479) - fix: return correct package specs when resolving workspace deps (rust-lang/cargo#17469) - refactor(config): Consolidate more config table definitions (rust-lang/cargo#17480) - fix(git): For git cli, tell users what config we aren't forwarding on error (rust-lang/cargo#17477) - Lower the lint level of `manual_readme` and `non_kebab_case_bins` to `allow` (rust-lang/cargo#17478) - fix(trim-paths)!: unremap file in one JSON doc (rust-lang/cargo#17476) - feat(manifest): support `feature-documentation` in manifests (rust-lang/cargo#17447) - chore: Add Muscraft to the review rotation (rust-lang/cargo#17471) - Specify `--edition` in `messages` tests (rust-lang/cargo#17470) r? Urgau for the debugger script part --- 🤖 LLM disclosure: I probably should have tested this change manually, though I let LLM verify it working, sorry. Will do a manual test when I have time or if somebody beats me on that.

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

Comment thread doc/book/src/reference/unstable.md

Comment thread doc/book/src/reference/unstable.md

weihanglo approved these changes Sep 7, 2026

View reviewed changes

docs(unstable): feature-metadata is the umbrella feature

223796b

weihanglo force-pushed the feat/rfc-impl-feature-documentation-schema branch from aee401e to 223796b Compare September 14, 2026 14:57

weihanglo enabled auto-merge September 14, 2026 14:59

weihanglo added this pull request to the merge queue Sep 14, 2026

Merged via the queue into rust-lang:master with commit cc5596f Sep 14, 2026
29 checks passed

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

weihanglo mentioned this pull request Sep 14, 2026

Tracking Issue for feature-documentation #17445

Open

2 tasks

weihanglo added the Z-feature-metadata Nightly: feature-metadata label Sep 14, 2026

weihanglo mentioned this pull request Sep 15, 2026

Update cargo submodule rust-lang/rust#162823

Merged

AudaciousAxiom deleted the feat/rfc-impl-feature-documentation-schema branch September 16, 2026 15:29

rustbot added this to the 1.100.0 milestone Sep 16, 2026

	/// 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!

weihanglo Sep 6, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo Sep 6, 2026

Choose a reason for hiding this comment

Uh oh!

AudaciousAxiom Sep 6, 2026

Choose a reason for hiding this comment

Uh oh!

0xPoe Sep 6, 2026

Choose a reason for hiding this comment

Uh oh!

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!

weihanglo Sep 6, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo Sep 6, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo Sep 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

AudaciousAxiom Sep 6, 2026 •

edited by rustbot

Loading

weihanglo left a comment •

edited by rustbot

Loading

weihanglo left a comment •

edited by rustbot

Loading