Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

RFC: Unblock Cargo feature metadata #3416

Merged
merged 45 commits into from
Jun 27, 2024

Conversation

tgross35
Copy link
Contributor

@tgross35 tgross35 commented Apr 15, 2023

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

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:

The following were deferred out:

@ehuss ehuss added T-cargo Relevant to the Cargo team, which will review and decide on the RFC. T-rustdoc Relevant to rustdoc team, which will review and decide on the RFC. labels Apr 15, 2023
@tgross35 tgross35 closed this Apr 15, 2023
@tgross35 tgross35 deleted the feature-descriptions-doc-cfg branch April 15, 2023 21:12
@tgross35 tgross35 restored the feature-descriptions-doc-cfg branch April 15, 2023 21:13
@tgross35 tgross35 reopened this Apr 15, 2023
@tgross35
Copy link
Contributor Author

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.

@tgross35 tgross35 changed the title RFC: Feature descriptions & rustdoc configuration RFC: Cargo feature descriptions & rustdoc configuration Apr 16, 2023
@blyxyas
Copy link
Member

blyxyas commented Apr 16, 2023

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
Copy link
Contributor Author

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
Copy link
Member

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
Copy link
Contributor Author

@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
Copy link
Contributor Author

tgross35 commented Sep 9, 2023

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 epage changed the title RFC: Cargo feature descriptions & metadata RFC: Unblock Cargo feature metadata May 21, 2024
@epage epage removed the T-rustdoc Relevant to rustdoc team, which will review and decide on the RFC. label May 21, 2024
@epage
Copy link
Contributor

epage commented Jun 11, 2024

@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
Copy link
Collaborator

rfcbot commented Jun 11, 2024

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

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.

@rfcbot 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 11, 2024
@tgross35
Copy link
Contributor Author

@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 rfcbot added final-comment-period Will be merged/postponed/closed in ~10 calendar days unless new substational objections are raised. and removed proposed-final-comment-period Currently awaiting signoff of all team members in order to enter the final comment period. labels Jun 14, 2024
@rfcbot
Copy link
Collaborator

rfcbot commented Jun 14, 2024

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

@rfcbot rfcbot added finished-final-comment-period The final comment period is finished for this RFC. to-announce and removed final-comment-period Will be merged/postponed/closed in ~10 calendar days unless new substational objections are raised. labels Jun 24, 2024
@rfcbot
Copy link
Collaborator

rfcbot commented Jun 24, 2024

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
Copy link
Contributor

epage commented Jun 27, 2024

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

@epage epage merged commit 9fe5140 into rust-lang:master Jun 27, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
disposition-merge This RFC is in PFCP or FCP with a disposition to merge it. finished-final-comment-period The final comment period is finished for this RFC. T-cargo Relevant to the Cargo team, which will review and decide on the RFC. to-announce
Projects
Archived in project
Status: Unreviewed
Development

Successfully merging this pull request may close these issues.