RFC: Cargo feature descriptions #3485

tgross35 · 2023-09-09T22:59:28Z

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 · 2023-09-09T22:59:41Z

@rustbot label +t-cargo

rustbot · 2023-09-09T22:59:42Z

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.

I directly applied my more minor feedback that did not change the characteristic of the RFC.

epage · 2023-09-10T01:35:55Z

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

epage · 2023-09-10T01:38:21Z

text/3485-feature-documentation.md

+- Rather than being consistent with `rustdoc` and accepting markdown, should the
+ `doc` key be consistent with `package.description` and only support plain


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.

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.

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

text/3485-feature-documentation.md

weihanglo · 2023-09-15T19:45:29Z

text/3485-feature-documentation.md

+
+This RFC describes a new key to under `features` in `Cargo.toml` for
+documentation. This will allow Cargo to display this information to the user and
+provide a way for `rustdoc` to eventually render this data (how this is rendered


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.

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

@rustbot

This is allowed in [`rust-lang/rust`](https://github.com/rust-lang/rust/blob/62d9034a0d571b78e518727d6cb4b090569e5238/triagebot.toml#L12). Others have also expected it to work here: - rust-lang#3490 (comment) - rust-lang#3485 (comment) @rustbot label not-rfc

text/3485-feature-documentation.md

joshtriplett · 2024-06-21T01:58:43Z

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 · 2024-06-21T01:58:52Z

@rfcbot merge

rfcbot · 2024-06-21T01:59:06Z

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

Concerns:

cargo-metadata (RFC: Cargo feature descriptions #3485 (comment))
~~docs-included-in-design~~ resolved by RFC: Cargo feature descriptions #3485 (comment)
naming (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.

text/3485-feature-documentation.md

weihanglo · 2024-06-22T13:29:05Z

@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 · 2024-06-22T14:02:49Z

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

GuillaumeGomez · 2024-06-22T14:04:28Z

text/3485-feature-documentation.md

+# Tables are preferred for longer descriptions
+[features.corge]
+enables = ["bar", "baz"]
+doc = """


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?

Ah I see you mentioned it below, my bad.

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.

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?

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.

Added, thank you!

text/3485-feature-documentation.md

epage · 2024-07-09T16:24:32Z

text/3485-feature-documentation.md

+
+[guide-level-explanation]: #guide-level-explanation
+
+A new `doc` key will be allowed within a feature's table. This key provides a


Naming (not finding the past discussion on it)

doc mirrors #[doc(...)]

description mirrors package.description

documentation mirrors package.documentation (but that is a URL)

We also tend to not use abbreviations as much. For example, for public-private dependencies, we discussed using pub vs public and went with public

@epage In my opinion, I think this should be doc.

I think we should encourage using this not just for a "description" of a feature but for "documentation" for a feature, and that's supported by the idea of it showing up in rustdoc and allowing markdown.

And I think there's a big difference in length between doc and documentation, compared to the difference between pub and public. (I personally would have gone with pub for that too, based on widespread usage of pub within Rust, but I also think public was less obtrusive because it's fewer characters.)

It's hard enough to get people to write documentation; let's not have any extra friction.

(I personally would have gone with pub for that too, based on widespread usage of pub within Rust, but I also think public was less obtrusive because it's fewer characters.)

Personally, I'd prefer we be consistent and not just focusing on character count.

It's hard enough to get people to write documentation; let's not have any extra friction.

We've shot well past that by requiring a "long form" just to write documentation, hurting both discoverability, character count, and ease of not typing some of those characters on international keyboards.

text/3485-feature-documentation.md

epage · 2024-07-09T18:04:48Z

@rfcbot concern naming

See my comment

Co-authored-by: Josh Triplett <[email protected]>

Co-authored-by: Ed Page <[email protected]>

Co-authored-by: Josh Triplett <[email protected]>

Co-authored-by: Ed Page <[email protected]>

Eh2406 · 2024-07-15T14:02:10Z

This technically avoids promising work from the rustdoc and docs.rs teams, but that seems like a technicality. The obvious follow-up is for those teams to do something with this information. I have been in adequately following the conversation here. Have they been consulted? Given that none of the technical details have been decided, I don't think their checkboxes should be required, but I also don't want this to be a surprise to them.

@rfcbot concern docs-included-in-design

(Anyone should feel free to resolve this concern if members of those teams have been consulted.)

GuillaumeGomez · 2024-07-15T14:09:53Z

In the case of docs.rs, it has access to more information so it's not really an issue. The big unknown here is how this information could be given to rustdoc. I suppose through a command-line argument. My only worry about this solution is about the command-line argument size limitation. However, it can be completely nullified by using an @ argument. So I don't see any blocker from rustdoc side either (on how to provide this information).

The big discussion will actually be: how do we display this information in the generated documentation?

syphar · 2024-07-15T14:12:23Z

This technically avoids promising work from the rustdoc and docs.rs teams, but that seems like a technicality. The obvious follow-up is for those teams to do something with this information. I have been in adequately following the conversation here. Have they been consulted? Given that none of the technical details have been decided, I don't think their checkboxes should be required, but I also don't want this to be a surprise to them.

I do follow this PR from the sidelines, though not all the discussion on here.

( also, @GuillaumeGomez already said what I wanted to say)

Eh2406 · 2024-07-15T14:14:43Z

@rfcbot resolve docs-included-in-design

obi1kenobi · 2024-07-15T14:18:16Z

The big discussion will actually be: how do we display this information in the generated documentation?

Tangentially: I hope this information might also become available in rustdoc JSON one day, for the benefit of tools like cargo-semver-checks. It's possible to cause semver breakage by changing crate features, and right now, detecting such breakage requires parsing the Cargo.toml file which can be trickier than it may seem at first.

GuillaumeGomez · 2024-07-15T14:34:49Z

You can ping me directly if it's not there but it's present in the HTML doc. I'll add it as fast as I can if I forgot. ;)

syphar · 2024-07-15T14:50:16Z

The big discussion will actually be: how do we display this information in the generated documentation?

and following from there, what happens to the docs.rs view, especially since we also have rust-lang/docs.rs#2530 and rust-lang/docs.rs#2531

tgross35 · 2024-07-15T17:24:17Z

In the case of docs.rs, it has access to more information so it's not really an issue. The big unknown here is how this information could be given to rustdoc. I suppose through a command-line argument. My only worry about this solution is about the command-line argument size limitation. However, it can be completely nullified by using an @ argument. So I don't see any blocker from rustdoc side either (on how to provide this information).

Does rustdoc already have access to the output of cargo metadata? If so, I think this should eventually wind up there even though I didn't mention it in this RFC (@epage does it seem reasonable to add it?).

I had a draft RFC for a schema to give rustdoc this information if some non-Cargo tool wants to make use of the features display, but would probably need to rework it a ton at this point #3421

The big discussion will actually be: how do we display this information in the generated documentation?

I preemptively opened a tracking issue for rustdoc support and will put some ideas there (I am sure you have some already too :) ) rust-lang/rust#127771. Also noted JSON support as something to consider from @obi1kenobi's comment.

The big discussion will actually be: how do we display this information in the generated documentation?

and following from there, what happens to the docs.rs view, especially since we also have rust-lang/docs.rs#2530 and rust-lang/docs.rs#2531

I don't know what would happen to the docs.rs view; there doesn't seem to be much harm in keeping it but maybe also not much sense in augmenting it much further if rustdoc will begin to cover it? Those issues could likely be addressed in whatever rustdoc winds up generating here.

GuillaumeGomez · 2024-07-15T17:40:57Z

In the case of docs.rs, it has access to more information so it's not really an issue. The big unknown here is how this information could be given to rustdoc. I suppose through a command-line argument. My only worry about this solution is about the command-line argument size limitation. However, it can be completely nullified by using an @ argument. So I don't see any blocker from rustdoc side either (on how to provide this information).

Does rustdoc already have access to the output of cargo metadata? If so, I think this should eventually wind up there even though I didn't mention it in this RFC (@epage does it seem reasonable to add it?).

Easy answer: same as rustc (so no as far as I know).

The big discussion will actually be: how do we display this information in the generated documentation?

I preemptively opened a tracking issue for rustdoc support and will put some ideas there (I am sure you have some already too :) ) rust-lang/rust#127771. Also noted JSON support as something to consider from @obi1kenobi's comment.

👍

The big discussion will actually be: how do we display this information in the generated documentation?

and following from there, what happens to the docs.rs view, especially since we also have rust-lang/docs.rs#2530 and rust-lang/docs.rs#2531

I don't know what would happen to the docs.rs view; there doesn't seem to be much harm in keeping it but maybe also not much sense in augmenting it much further if rustdoc will begin to cover it? Those issues could likely be addressed in whatever rustdoc winds up generating here.

docs.rs and rustdoc are tangent. They can both provide an information in different ways.

epage · 2024-07-15T19:36:53Z

I think this should eventually wind up [in cargo metadata] even though I didn't mention it in this RFC (@epage does it seem reasonable to add it?).

So while this isn't relevant for #3421, this is a good point more generally and one we overlooked in #3416. We need to decide if we want to include this in cargo metadata and what that schema would look like. Would we need a parallel structure? Update the format version?

@rfcbot concern cargo-metadata

tgross35 · 2024-07-15T23:27:14Z

I think this should eventually wind up [in cargo metadata] even though I didn't mention it in this RFC (@epage does it seem reasonable to add it?).

So while this isn't relevant for #3421, this is a good point more generally and one we overlooked in #3416. We need to decide if we want to include this in cargo metadata and what that schema would look like. Would we need a parallel structure? Update the format version?

@rfcbot concern cargo-metadata

The most elegant schema would be to mirror these tables directly into metadata. That is, update:

"features": {
    "foo": ["bar"],
    "bar": [],
    "baz": []
}

To be something like:

"features": {
    "foo": { "enables": ["bar"], "doc": "Enable wxyz" },
                               // ^ bikeshed still being built
    "bar": { "enables": [], "doc": "Make use of ..." },
    "baz": { "enables": [] } // < only having one serialization seems easier than allowing
                             // `"bar": []`, but doesn't matter much
}

However; being that Cargo needs to support all possible schema versions forever (as I understand it), it seems like the barrier for a breaking schema change is quite high. So maybe we should add a new features_metadata object next to features that adds this information in a redundant but backward-compatible way. And then just put replacing features with features_metadata on a "wanted for v2" list for whenever there is enough to justify the new version.

amab8901 · 2024-08-17T18:46:11Z

why is this PR still open if the parent is closed?

tgross35 · 2024-08-17T18:55:05Z

why is this PR still open if the parent is closed?

The RFC you linked only establishes a format for adding more metadata to features, it doesn't actually confirm that we want to add anything specific. This RFC is about adding documentation as part of metadata, but needs resolution to the two listed concerns.

@epage does #3485 (comment) sound reasonable? If so, I will update the RFC.

If accepted here we may want to consider updating #3416 so that the feature schema isn't provided only in the documentation RFC - obviously up to you to weigh that vs. updating an accepted RFC.

epage · 2024-08-19T14:35:36Z

@tgross35

The most elegant schema would be to mirror these tables directly into metadata.
That is, update:

<simple form>

To be something like:

<detailed form>

However; being that Cargo needs to support all possible schema versions forever (as I understand it), it seems like the barrier for a breaking schema change is quite high.

As these details seem to be implicit, you are saying this would be a new --format-version <VERSION>?

Yes, 'wed need to support generating data for all possible schemas for ever.

Pulled in your ideas and added some more. Mind adding this to the RFC alternatives and documenting which you think we should go with and why? We can then discuss it in a cargo team meeting.

A new message format version

We either deprecate the current version, making new features all-or-nothing, or need to add features to both versions

As the format-version is defaulted (with a warning), we'd need to consider what the migration path would be to v2.

A parallel table for just this

This is your features_metadata.

We need to do this for every new field. While #3663 was closed, doing something like that would put coupled data in parallel tables.

A new `features2` or `features-detailed`

Automatically gets new data.

Seems inelegant but that isn't necessarily a blocker.

Use simple form where possible

Technically, this gets us into the territory of "forwards compatibility" rather than "backwards compatibility", ie things break when new features are used with old tools rather than breaking existing features on new tools.

We'd need to make sure we render in the "simple" format whenever we can.

This can still be disruptive to the ecosystem. serde handles adding of new fields well (ignore) but not changing of data types (error). Most people go through cargo_metadata so we'd likely only need to implement things once and then people just need to update.

Add initial feature-documentation RFC split from feature-metadata

7aa7df0

compiler-errors added the T-cargo Relevant to the Cargo team, which will review and decide on the RFC. label Sep 9, 2023

Update RFC number

c52bd96

tgross35 mentioned this pull request Sep 9, 2023

RFC: Unblock Cargo feature metadata #3416

Merged

Misc cleanup

51400c5

I directly applied my more minor feedback that did not change the characteristic of the RFC.

epage reviewed Sep 10, 2023

View reviewed changes

text/3485-feature-documentation.md Outdated Show resolved Hide resolved

Make it clear that a decision on markdown has not yet been reached

129ab25

weihanglo reviewed Sep 15, 2023

View reviewed changes

eopb mentioned this pull request Sep 20, 2023

unauthenticated @rustbot label T-* #3494

Merged

Nemo157 mentioned this pull request Feb 21, 2024

Adding one more tab for crate's features rust-lang/docs.rs#2405

Closed

epage reviewed May 21, 2024

View reviewed changes

text/3485-feature-documentation.md Show resolved Hide resolved

joshtriplett reviewed Jun 21, 2024

View reviewed changes

text/3485-feature-documentation.md Outdated Show resolved Hide resolved

rfcbot added proposed-final-comment-period Currently awaiting signoff of all team members in order to enter the final comment period. disposition-merge This RFC is in PFCP or FCP with a disposition to merge it. labels Jun 21, 2024

joshtriplett reviewed Jun 21, 2024

View reviewed changes

text/3485-feature-documentation.md Outdated Show resolved Hide resolved

GuillaumeGomez reviewed Jun 22, 2024

View reviewed changes

epage mentioned this pull request Jun 27, 2024

Tracking Issue for feature-metadata rust-lang/cargo#14157

Open

epage reviewed Jul 9, 2024

View reviewed changes

text/3485-feature-documentation.md Outdated Show resolved Hide resolved

epage reviewed Jul 9, 2024

View reviewed changes

text/3485-feature-documentation.md Outdated Show resolved Hide resolved

epage reviewed Jul 9, 2024

View reviewed changes

text/3485-feature-documentation.md Outdated Show resolved Hide resolved

epage reviewed Jul 9, 2024

View reviewed changes

text/3485-feature-documentation.md Outdated Show resolved Hide resolved

tgross35 and others added 5 commits July 9, 2024 14:06

Update text/3485-feature-documentation.md

326b4d9

Co-authored-by: Josh Triplett <[email protected]>

Update text/3485-feature-documentation.md

6a793f5

Co-authored-by: Ed Page <[email protected]>

Update text/3485-feature-documentation.md

4957dd0

Co-authored-by: Ed Page <[email protected]>

Update text/3485-feature-documentation.md

9cc3334

Co-authored-by: Josh Triplett <[email protected]>

Update text/3485-feature-documentation.md

9d87695

Co-authored-by: Ed Page <[email protected]>

rimutaka mentioned this pull request Jul 12, 2024

Error handling improvements awslabs/aws-lambda-rust-runtime#907

Merged

4 tasks

tgross35 added 3 commits July 15, 2024 11:55

Add note about rustdoc support of links

b6d13a6

Apply formatting

c330adb

Add an example in the summary

b2b27a2

tgross35 mentioned this pull request Jul 15, 2024

Tracking Issue for Rustdoc support of RFC3485 feature-documentation rust-lang/rust#127771

Open

6 tasks

		- Rather than being consistent with `rustdoc` and accepting markdown, should the
		`doc` key be consistent with `package.description` and only support plain


		[guide-level-explanation]: #guide-level-explanation

		A new `doc` key will be allowed within a feature's table. This key provides a

RFC: Cargo feature descriptions #3485

Are you sure you want to change the base?

RFC: Cargo feature descriptions #3485

Conversation

tgross35 commented Sep 9, 2023 • edited by epage Loading

tgross35 commented Sep 9, 2023

rustbot commented Sep 9, 2023

epage commented Sep 10, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joshtriplett commented Jun 21, 2024

joshtriplett commented Jun 21, 2024

rfcbot commented Jun 21, 2024 • edited by arlosi Loading

weihanglo commented Jun 22, 2024 • edited Loading

GuillaumeGomez commented Jun 22, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

weihanglo Jun 22, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

epage commented Jul 9, 2024 • edited Loading

Eh2406 commented Jul 15, 2024

GuillaumeGomez commented Jul 15, 2024

syphar commented Jul 15, 2024

Eh2406 commented Jul 15, 2024

obi1kenobi commented Jul 15, 2024

GuillaumeGomez commented Jul 15, 2024

syphar commented Jul 15, 2024

tgross35 commented Jul 15, 2024 • edited Loading

GuillaumeGomez commented Jul 15, 2024

epage commented Jul 15, 2024

tgross35 commented Jul 15, 2024 • edited Loading

amab8901 commented Aug 17, 2024

tgross35 commented Aug 17, 2024 • edited Loading

epage commented Aug 19, 2024

A new message format version

A parallel table for just this

A new features2 or features-detailed

Use simple form where possible

tgross35 commented Sep 9, 2023 •

edited by epage

Loading

rfcbot commented Jun 21, 2024 •

edited by arlosi

Loading

weihanglo commented Jun 22, 2024 •

edited

Loading

weihanglo Jun 22, 2024 •

edited

Loading

epage commented Jul 9, 2024 •

edited

Loading

tgross35 commented Jul 15, 2024 •

edited

Loading

tgross35 commented Jul 15, 2024 •

edited

Loading

tgross35 commented Aug 17, 2024 •

edited

Loading

A new `features2` or `features-detailed`