Skip to content

docs(book): document the table syntax of features - #17446

Draft
AudaciousAxiom wants to merge 2 commits into
rust-lang:masterfrom
AudaciousAxiom:docs/book-features-table-syntax
Draft

docs(book): document the table syntax of features#17446
AudaciousAxiom wants to merge 2 commits into
rust-lang:masterfrom
AudaciousAxiom:docs/book-features-table-syntax

Conversation

@AudaciousAxiom

Copy link
Copy Markdown
Contributor

What does this PR try to resolve?

This is a follow-up to #15056 (comment), and part of feature-metadata #14157, that prepares the documentation for when the unstable feature (or the first of its subfeatures) is eventually stabilized (I understand this is not for now, and that this PR will very likely conflict). Sometimes documentation stemming from unstable features can be added to the documentation of the unstable feature itself, as suggested in #15056 (comment), but I think this doesn't really work in this case as this is not purely additive.

This should address all occurrences within the book; this can be checked with rg -A1 '\[features\]' doc/book/.

Open questions

  • How should the table syntax be articulated in the docs to the existing array syntax? What this PR currently proposes is to make the new table syntax the new default way of defining features (because I think we want to encourage authors to document their features through the now-accepted feature-documentation), and only documents the old array syntax as a shortcut.

How to test and review this PR?

This is a doc-only PR. It's kept as draft until the first subfeature of feature-metadata is stabilized. Doing this early helped me find a corner-case in feature-visibility. Feel free to edit this PR as needed.

@rustbot rustbot added the A-documenting-cargo-itself Area: Cargo's documentation label Sep 6, 2026
## The `[features]` section

Features are defined in the `[features]` table in `Cargo.toml`. Each feature
specifies an array of other features or optional dependencies that it enables.

@AudaciousAxiom AudaciousAxiom Sep 6, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe the reference to the array might need to be updated, but the list of features itself is at least still an array.

View changes since the review

@weihanglo weihanglo Sep 6, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A good idea of this documentation hasn't yet come up in my mind. There are things that we want to take into considerations:

  • We need to explicitly say that which MSRV supports this, like other manifest fields that has a MSRV: quote block
  • We may also want to advocate writing feature documentation in the future, so we actually love to see people migrating to new syntax.

I feel like the two points contradict to each other 😞.

View changes since the review

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-documenting-cargo-itself Area: Cargo's documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants