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: Cargo feature descriptions #3485
base: master
Are you sure you want to change the base?
Changes from 3 commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,196 @@ | ||
- Feature Name: feature-documentation | ||
- Start Date: 2023-09-09 | ||
- RFC PR: [rust-lang/rfcs#3485](https://github.com/rust-lang/rfcs/pull/3485) | ||
- Rust Issue: | ||
[rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) | ||
|
||
# Summary | ||
|
||
[summary]: #summary | ||
|
||
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 | ||
is outside the scope of this RFC). | ||
|
||
Please see the parent meta RFC for background information: [`feature-metadata`]. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This RFC is blocked on |
||
|
||
# Motivation | ||
|
||
[motivation]: #motivation | ||
|
||
Cargo features have become extremely widely used, with many crates having at | ||
least some level of configuration and larger crates winding up with tens of | ||
gates. Desipte being a first class component of crate structure, they suffer | ||
from a documentation problem: users need to maintain documentation separate from | ||
feature definition, typically a manually-created table within API docs. | ||
|
||
This RFC proposes adding feature documentation to `Cargo.toml`, which will allow | ||
for keeping feature definitions and documentation together. | ||
|
||
# Guide-level explanation | ||
|
||
[guide-level-explanation]: #guide-level-explanation | ||
|
||
A new `doc` key will be allowed within a feature's table. This key provides a | ||
markdown docstring describing the feature. Like with `#[doc(...)]`, the first | ||
line will be treated as a summary. | ||
|
||
```toml | ||
[features] | ||
# Feature without documentation | ||
foo = [] | ||
|
||
# Short documentation comment | ||
bar = { enables = ["foo"], doc = "simple docstring here"} | ||
|
||
# Tables are preferred for longer descriptions | ||
[features.corge] | ||
enables = ["bar", "baz"] | ||
doc = """ | ||
# corge | ||
|
||
This could be a longer description of this feature | ||
""" | ||
``` | ||
|
||
See [`feature-metadata`] for information about `enables`. | ||
|
||
# Reference-level explanation | ||
|
||
[reference-level-explanation]: #reference-level-explanation | ||
|
||
The new `doc` key accepts markdown-flavored text, and should be thought of as | ||
the equivalent to a `#[doc(...)]` attribute. Like doc comments, the first line | ||
should be treated as a summary. Intra-doc link support is not included in this | ||
RFC, so they should not be used. | ||
|
||
There is nothing in this RFC that cargo **must** do with this action, since it is | ||
mainly intended for the consumption of `rustdoc` or `docs.rs`. However, it can | ||
be used for general diagnostic information such as during `cargo add` or a | ||
possible `cargo info` command. A sample application with `cargo add`: | ||
|
||
```text | ||
crab@rust foobar % cargo add regex | ||
Updating crates.io index | ||
Adding regex v1.7.3 to dependencies. | ||
Features: | ||
+ perf Enables all performance related features | ||
+ perf-dfa Enables the use of a lazy DFA for matching | ||
+ perf-inline Enables the use of aggressive inlining inside | ||
match routines | ||
+ perf-literal Enables the use of literal optimizations for | ||
speeding up matches | ||
+ std When enabled, this will cause regex to use the | ||
standard library | ||
+ unicode Enables all Unicode features | ||
|
||
Updating crates.io index | ||
``` | ||
|
||
*(features like `aho-corasick`, `memchr`, or `use_std` would likely be | ||
`public = false` since they aren't listed on the crate landing page)* | ||
|
||
Any tools that want the information in `doc` will require access to the | ||
manifest. Adding this information to the index was decided against due to | ||
concerns about bloat, but this is further discussed in | ||
[future possibilities][future-possibilities]. | ||
|
||
# Drawbacks | ||
|
||
[drawbacks]: #drawbacks | ||
|
||
- Added complexity to Cargo. | ||
- Exact implementation details do add test surface area | ||
- A markdown parser is required to properly parse the `doc` field. | ||
- Docstrings can be lengthy, adding noise to `Cargo.toml`. This could | ||
potentially be solved with the below mentioned `doc-file` key. | ||
- When rendering features in documentation, this RFC does not specify any way | ||
for `rustdoc` to get the information it requires. This will require separate | ||
design work. | ||
- Unlike with the [`document-features`](https://crates.io/crates/document-features) | ||
crate there is no way to group features in into sections or have a | ||
user-specified layout | ||
- Users cannot control features ordering in documentation since the TOML specification defines table keys as unordered. | ||
|
||
# Rationale and alternatives | ||
|
||
[rationale-and-alternatives]: #rationale-and-alternatives | ||
|
||
- To avoid increasing the size of the registry index, this does not add `doc` | ||
to a package's index entry. This means a `.crate` file must be downloaded | ||
and extracted to access the features. | ||
- Feature descriptions could be specified somewhere in Rust source files. This | ||
has the downside of creating multiple sources of truth on features. | ||
- Cargo could parse doc comments in `Cargo.toml`, like the `document-features` | ||
crate (linked below). | ||
|
||
```toml | ||
# RFC proposal | ||
foo = { enables = [], doc = "foo feature" } | ||
|
||
# Alternative equivalent using doc comments | ||
## foo feature | ||
foo = [] | ||
``` | ||
|
||
This was decided against as part of this RFC because it would mean that | ||
TOML-compliant parsers (including anything `serde`-based) would be | ||
insufficient to extract all information in the manifest, requiring custom | ||
deserialization of the fields via a format-preserving parser. This differs | ||
from documentation in Rust source as the doc-comment behavior is described | ||
specified within the grammar with parsers supporting extracting those | ||
elements. | ||
|
||
# Prior art | ||
|
||
[prior-art]: #prior-art | ||
|
||
- There is an existing crate that uses TOML comments to create a features table: | ||
<https://docs.rs/document-features/latest/document_features/> | ||
- `docs.rs` displays a feature table, but it is fairly limited. If features | ||
start with `_`, they are hidden from this table ([example](https://docs.rs/crate/regex/latest/features)). | ||
- `lib.rs` extracts feature documentation from `Cargo.toml` and source ([example](https://lib.rs/crates/regex/features)) | ||
|
||
# Unresolved questions | ||
|
||
[unresolved-questions]: #unresolved-questions | ||
|
||
- Rather than being consistent with `rustdoc` and accepting markdown, should the | ||
`doc` key be consistent with `package.description` and only support plain | ||
Comment on lines
+159
to
+160
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Wanted to highlight this for discussion. My main interest is in being able to show summaries in There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Package descriptions tend to use markdown 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. |
||
text? This RFC proposes making this decision at time of implementation when the | ||
challenges of supporting markdown are better understood. | ||
|
||
tgross35 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
# Future possibilities | ||
|
||
[future-possibilities]: #future-possibilities | ||
|
||
- Rustdoc can build on this to show feature documentation. | ||
- At some point, the decision to not include `doc` in the index could be | ||
reevaluated. Including only the first (summary) line of `doc` could be a | ||
possibility. | ||
- `cargo add` can show the `doc` and `deprecated` summary with the listed | ||
features. | ||
- [`cargo-info`] can use this information to provide feature descriptions. | ||
- crates-io could be updated to render feature documentation | ||
- Feature documentation could be allowed in a separate markdown file. For | ||
convenience, markdown anchors could be used to specify a section, so multiple | ||
features can share the same file. This could be a good option for features | ||
requiring long descriptions. | ||
|
||
```toml | ||
foo = { enables = [], doc-file = "features.md#foo" } | ||
bar = { enables = [], doc-file = "features.md#bar" } | ||
``` | ||
|
||
[cargo #12335]: https://github.com/rust-lang/cargo/issues/12235 | ||
[cargo #10882]: https://github.com/rust-lang/cargo/issues/10882 | ||
[`cargo-info`]: https://github.com/rust-lang/cargo/issues/948 | ||
[`deprecated`]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute | ||
[`deprecated-suggestions`]: https://github.com/rust-lang/rust/issues/94785 | ||
[discussion on since]: https://github.com/rust-lang/rfcs/pull/3416#discussion_r1172895497 | ||
[`public_private_dependencies`]: https://rust-lang.github.io/rfcs/1977-public-private-dependencies.html | ||
[`rustdoc-cargo-configuration`]: https://github.com/rust-lang/rfcs/pull/3421 | ||
[`tokio`]: https://docs.rs/crate/tokio/latest/features | ||
[visibility attribute]: https://ant.apache.org/ivy/history/latest-milestone/ivyfile/conf.html | ||
[`feature-metadata`]: https://github.com/rust-lang/rfcs/pull/3416 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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