RFC: Unblock Cargo feature metadata

[tgross35]

NOTE: At @epage's suggestion I split this into three different RFCs:

• RFC: Cargo feature descriptions #3485
• RFC: Cargo feature deprecation #3486
• RFC: Cargo feature visibility (private/public) #3487

I will leave this one open as a meta RFC for now

---

Rendered

RFC for feature-metadata
RFC goals: add a way to write feature descriptions and other feature configuration in Cargo.toml. #3421 will provide a way for rustdoc to use that information.

# Cargo.toml snippet

[features]
# current configuration
foo = []
# Add a description to the feature
bar = { enables = ["foo"], doc = "simple docstring here"}
# `public` indicates whether or not the feature should be visible in
# documentation, and defaults to true
baz = { enables = ["foo"], public = false }

# Features can also be full tables if descriptions are longer
[features.qux]
enables = ["bar", "baz"]
doc = """
# qux

This could be a longer description of this feature
"""

Zulip discussion: https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/Descriptions.20for.20feature.20flags

This would resolve:

• Allow adding a description for features cargo#4956
• private/hidden features cargo#10882
• Feature Request: A way to deprecate features cargo#7130

The following were deferred out:

• stable/unstable/nightly-only features cargo#10881

[tgross35]

Whoops, didn't mean to accidentally close.

Anyway, I've finished filling out all the sections and I think this is ready enough for review. I'll mark it as such and ping the related issues to see if anyone has feedback to drop here.

[blyxyas]

Please note that the crate document-features already does this. Maybe it's worth it checking an existing implementation for some ideas (Like using ## as an equivalent to ///)

[tgross35]

Please note that the crate document-features already does this. Maybe it's worth it checking an existing implementation for some ideas (Like using ## as an equivalent to ///)

The crate is listed under the prior art section, and it also as future possibilities to support some sort of syntax like that. I do think it's a good idea to start with a doc TOML key since it's quite a bit easier to work with (and a lot less bikeshedable), but in the future a doc comment format could be added.

[shepmaster]

I'd like to replace SNAFU's documentation page for feature flags with something more automated. From that perspective, I'm not seeing this RFC describe what rustdoc is going to do with the information, how it will consumed by human beings, etc.

[tgross35]

@jsha mentioned a few possibilities on zulip for what to do with this information:

• top level of the crate, alongside all.html
• section of the main page for the crate, alongside Structs, Modules, etc
• have a macro someone could use to insert a set of documented feature flags at some point in their docs

Any of which make sense to me. The page you linked looks quite nice to me, and could serve as a good example for what rustdoc might do, and also brings up a good point that links to features should be expected to work (I will update the RFC later with notes on this)

I don't know whether the exact output of rustdoc should be within the scope of this RFC, just because that's likely open to more bikeshedding and will just need some trial/error of what looks good. So when I update the RFC I'll just add some open wording like the below, if that seems reasonable

This RFC does not intend to determine the exact user-facing output of rustdoc with feature information. However, it is expected that the rendered output will accomplish the following:

• Render all feature flags not marked public = false in a table or sectional format in a way that can be navigated to from the main page
• Allow linking to feature flags directly
• Indicate deprecated feature flags in some way
• Treat the first line of the description as a summary and the rest as body text (similar to how documenting other items currently works)

[tgross35]

Thanks for waking this up @kornelski, kept falling off my todo list.

@epage I split this RFC into three as we had discussed, see the top post links. I also added you as a collaborator to my RFC repo if you want to go ahead and adjust any of the structure https://github.com/tgross35/rfcs

[epage]

@tgross35 I hope my direct edits are ok and aligned with what you are wanting here. I was trying to do some basic clean up and capturing of Cargo team discussions on this RFC.

Thank you for splitting up the RFCs as this made today's discussions much easier!

As for when to stabilize this, we were a bit undecided. Waiting until something needs this gives us more time for evaluating this. However, stabilizing this ASAP means we can more easily avoid MSRV bumps.

@rfcbot fcp merge

[rfcbot]

Team member @epage has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Eh2406
• @Muscraft
• @arlosi
• @ehuss
• @epage
• @joshtriplett
• @weihanglo

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[tgross35]

@tgross35 I hope my direct edits are ok and aligned with what you are wanting here. I was trying to do some basic clean up and capturing of Cargo team discussions on this RFC.

Very much so, thank you for moving this along!

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[epage]

Congrats! The @rust-lang/cargo team has decided to accept this RFC.

To track further discussion, subscribe to the tracking issue here:
rust-lang/cargo#14157