RFC: Cargo feature descriptions

[tgross35]

View all comments

Rendered

RFC for feature-documentation
RFC goals: add a way to write feature descriptions in Cargo.toml

This was split from #3416

[features]
# current configuration
foo = []
# Add a description to the feature
bar = { enables = ["foo"], doc = "simple docstring here"}

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

This would resolve rust-lang/cargo#4956

FCP

[tgross35]

@rustbot label +t-cargo

[rustbot]

Error: Label t-cargo can only be set by Rust team members

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #t-infra on Zulip.

[epage]

@tgross35 thanks for the access. Definitely makes it handy for the more trivial feedback.

[epage]

Wanted to highlight this for discussion. My main interest is in being able to show summaries in cargo add. Might be good to reach out to @kornelski for what they have seen of how features are documented through the ecosystem as that might help show potential requirements.

[kornelski]

Package descriptions tend to use markdown `code` and *emphasis*. Rust devs really like using ` everywhere. Even rustc uses ` in terminal error messages.

Markdown's goal is to look fine even when displayed as plain text.

You could define it as the first line being for CLI help, and the rest for docs. Analogous to how rustdoc handles doc comments.

[joshtriplett]

@kornelski 👍 for using markdown. And I think it makes sense to treat the first logical line (anything before the first double-newline) as a "short description", cutting off subsequent paragraphs in places where full documentation doesn't fit.

[weihanglo]

One of the issues is how rustdoc consumes the data. rust doc generally knows nothing about Cargo.toml. I would suggest taking #3123 as a reference to start a discussion on cargo-rustdoc integration of this. It doesn't need to be perfect but at least two teams should have some consensus.

[tgross35]

I did bring it up when I initially proposed this feature, https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/Descriptions.20for.20feature.20flags and then opened a draft RFC suggesting that rustdoc accept JSON configuration, which Cargo could pass it #3421. That didn't get too much traction, though. I will start that discussion back up

[joshtriplett]

Since RFC 3416 is in FCP, that unblocks this feature.

I'm going to go ahead and propose FCP here, and see how close we are to consensus.

Personally, I do think we should use markdown here. Markdown already looks reasonable in plain text, by design, and it gives crates.io and docs.rs and rustdoc something nicer to work with.

[joshtriplett]

@rfcbot merge

[rfcbot]

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

Concerns:

• cargo-metadata resolved by RFC: Cargo feature descriptions #3485 (comment)
• docs-included-in-design resolved by RFC: Cargo feature descriptions #3485 (comment)
• naming resolved by RFC: Cargo feature descriptions #3485 (comment)

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.

[weihanglo]

@rfcbot reviewed

Though I still want to call out that intra-doc links are important #3416 (review). CC @GuillaumeGomez if they have any opinion on this.

[GuillaumeGomez]

This is a very good point. Thanks for the ping!

[GuillaumeGomez]

Another good question raised was "should we also support intra-doc links in this documentation?". I personally think we should and make the context the same as the crate top-level. What do you think?

[GuillaumeGomez]

Ah I see you mentioned it below, my bad.

[weihanglo]

Thanks for the response!

The follow-up question from me would be: Is there any compatibility issues if we hadn't implemented this RFC and rustdoc change all together? If not then this RFC can safely go first.

[GuillaumeGomez]

I'm not sure. From cargo perspective, whether there are intra-doc links or not in this documentation doesn't matter. But it'll definitely need to be mentioned when support will be discussed in rustdoc.

For the current case, I think cargo should mention that intra-doc links may be supported when rustdoc support this option and that's it. What do you think?

[weihanglo]

Sounds good to me.

@tgross35 could you add something like this? (or whichever way you'd like to rephase this)

- Rustdoc can build on this to show feature documentation.
+ Rustdoc can build on this to show feature documentation.
+ If this RFC gets stabilized before any corresponding change in rustdoc,
+ its documentation should highlight that rustdoc may parse the description and support intra-doc links in the feature.
+ Users need to be aware of this potential incompatibility.

[tgross35]

Added, thank you!

[epage]

@weihanglo and @kornelski I moved your conversation into a thread in the hopes that it will make it easier to follow

[epage]

FYI I removed T-rustdoc from this RFC because this is the Cargo portion split out of #3421 which is now just T-rustdoc's side. T-rustdoc's input in this RFC is still important for how viable this is for allowing #3421 but I expect we'll have other clients of this as well, including ourselves. I was just thinking the other day how having the feature descriptions would be nice for cargo's new completions.

[GuillaumeGomez]

Sounds good to me at least, thanks!

[tgross35]

Unfortunately I've let this slip for two years, but I opened #4002 with a metadata proposal that can then be extended to this RFC pretty easily.

[tgross35]

If #4002 or similar merges, we will need to figure out how this shows up in metadata. With that proposal, this would be:

"features_v2": {
    "feat": { "doc": "simple docstring for bar" }
}

One question is what the key name should be. doc being consistent with the Cargo.toml makes sense, but this could also be a full name like documentation or description.

View changes since the review

[epage]

We talked about the active concerns in the RFC

• RFC: Cargo feature descriptions #3485 (comment)
• RFC: Cargo feature descriptions #3485 (comment)

Neither of those requires the community-wide input and are likely best figured out while we work through implementation and stabilization.

@tgross35 if you could record those as Unresolved Questions, we'll remove the blocking concerns, allowing FCP to commence on this RFC.

[tgross35]

Thanks for discussing, I have added those items as unresolved questions.

[epage]

@rfcbot resolve cargo-metadata
@rfcbot resolve naming

[rust-rfcbot]

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

[rust-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.

[weihanglo]

Thanks people! This has passed FCP. Merging (finally 🎉🎉🎉).

Further discussion would happen in rust-lang/cargo#17445. Subscribe to track the progress.