From 7aa7df076fede453402444f671005b18571b591f Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Sat, 9 Sep 2023 18:57:20 -0400 Subject: [PATCH 01/12] Add initial feature-documentation RFC split from feature-metadata --- text/0000-feature-documentation.md | 191 +++++++++++++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 text/0000-feature-documentation.md diff --git a/text/0000-feature-documentation.md b/text/0000-feature-documentation.md new file mode 100644 index 00000000000..85e9b777146 --- /dev/null +++ b/text/0000-feature-documentation.md @@ -0,0 +1,191 @@ +- Feature Name: feature-documentation +- Start Date: 2023-09-09 +- RFC PR: [rust-lang/rfcs#3416](https://github.com/rust-lang/rfcs/pull/3416) +- 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`]. + +# 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. Parsing is trivial, but exact implementation + details do add test surface area +- Docstrings can be lengthy, adding noise to `Cargo.toml`. This could + potentially be solved with the below mentioned `doc-file` key. +- A markdown parser is required to properly parse the `doc` field. +- 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. +- There is no way to structure features in a way that they are split into + sections or have a user-specified layout, unlike with the `document-features` + crate. +- Features cannot be ordered since the TOML specification does not allow it. + +# Rationale and alternatives + +[rationale-and-alternatives]: #rationale-and-alternatives + +- 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: + +- `docs.rs` displays a feature table, but it is fairly limited. If features + start with `_`, they are hidden from this table. + +# 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 + text? This RFC proposes making this decision at time of implementation, the + challenges of supporting markdown are better understood. + +# Future possibilities + +[future-possibilities]: #future-possibilities + +- Rustdoc will gain the ability to document features. +- 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. +- 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 From c52bd96c04e9e79f23933299d56f361712762eae Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Sat, 9 Sep 2023 19:01:46 -0400 Subject: [PATCH 02/12] Update RFC number --- ...0-feature-documentation.md => 3485-feature-documentation.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename text/{0000-feature-documentation.md => 3485-feature-documentation.md} (99%) diff --git a/text/0000-feature-documentation.md b/text/3485-feature-documentation.md similarity index 99% rename from text/0000-feature-documentation.md rename to text/3485-feature-documentation.md index 85e9b777146..56f562ef8f0 100644 --- a/text/0000-feature-documentation.md +++ b/text/3485-feature-documentation.md @@ -1,6 +1,6 @@ - Feature Name: feature-documentation - Start Date: 2023-09-09 -- RFC PR: [rust-lang/rfcs#3416](https://github.com/rust-lang/rfcs/pull/3416) +- 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) From 51400c5e8a50a983c93e7af9f123f5953a762f80 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Sat, 9 Sep 2023 20:34:38 -0500 Subject: [PATCH 03/12] Misc cleanup I directly applied my more minor feedback that did not change the characteristic of the RFC. --- text/3485-feature-documentation.md | 31 +++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/text/3485-feature-documentation.md b/text/3485-feature-documentation.md index 56f562ef8f0..e22056717f4 100644 --- a/text/3485-feature-documentation.md +++ b/text/3485-feature-documentation.md @@ -65,7 +65,7 @@ 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 +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`: @@ -88,8 +88,8 @@ crab@rust foobar % cargo add regex 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. +*(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 @@ -100,23 +100,26 @@ concerns about bloat, but this is further discussed in [drawbacks]: #drawbacks -- Added complexity to Cargo. Parsing is trivial, but exact implementation - details do add test surface area +- 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. -- A markdown parser is required to properly parse the `doc` field. - 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. -- There is no way to structure features in a way that they are split into - sections or have a user-specified layout, unlike with the `document-features` - crate. -- Features cannot be ordered since the TOML specification does not allow it. +- 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` @@ -146,7 +149,8 @@ concerns about bloat, but this is further discussed in - There is an existing crate that uses TOML comments to create a features table: - `docs.rs` displays a feature table, but it is fairly limited. If features - start with `_`, they are hidden from this table. + 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 @@ -154,20 +158,21 @@ concerns about bloat, but this is further discussed in - Rather than being consistent with `rustdoc` and accepting markdown, should the `doc` key be consistent with `package.description` and only support plain - text? This RFC proposes making this decision at time of implementation, the + text? This RFC proposes making this decision at time of implementation when the challenges of supporting markdown are better understood. # Future possibilities [future-possibilities]: #future-possibilities -- Rustdoc will gain the ability to document features. +- 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 From 129ab2512d03875daabf6037fb9019ec239c143f Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Fri, 15 Sep 2023 01:35:49 -0400 Subject: [PATCH 04/12] Make it clear that a decision on markdown has not yet been reached --- text/3485-feature-documentation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/text/3485-feature-documentation.md b/text/3485-feature-documentation.md index e22056717f4..b092625c3d8 100644 --- a/text/3485-feature-documentation.md +++ b/text/3485-feature-documentation.md @@ -158,8 +158,7 @@ concerns about bloat, but this is further discussed in - Rather than being consistent with `rustdoc` and accepting markdown, should the `doc` key be consistent with `package.description` and only support plain - text? This RFC proposes making this decision at time of implementation when the - challenges of supporting markdown are better understood. + text? This needs to be a point of discussion before approval of this RFC. # Future possibilities From 326b4d961bec7e9128a67ea5c5d90ac2ef9f0a49 Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Tue, 9 Jul 2024 14:06:15 -0400 Subject: [PATCH 05/12] Update text/3485-feature-documentation.md Co-authored-by: Josh Triplett --- text/3485-feature-documentation.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/text/3485-feature-documentation.md b/text/3485-feature-documentation.md index b092625c3d8..35f555212c7 100644 --- a/text/3485-feature-documentation.md +++ b/text/3485-feature-documentation.md @@ -33,8 +33,13 @@ for keeping feature definitions and documentation together. [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. +markdown docstring describing the feature. The first paragraph +will be treated as a summary, and should be suitable to display +standalone without the rest of the description. + +Don't include the name of the feature in the summary; tools +will typically already display this documentation alongside +the name of the feature. ```toml [features] From 6a793f516f20cfeaffed51671e029d340ad3526a Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Tue, 9 Jul 2024 14:06:27 -0400 Subject: [PATCH 06/12] Update text/3485-feature-documentation.md Co-authored-by: Ed Page --- text/3485-feature-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/3485-feature-documentation.md b/text/3485-feature-documentation.md index 35f555212c7..bf989551d3a 100644 --- a/text/3485-feature-documentation.md +++ b/text/3485-feature-documentation.md @@ -114,7 +114,7 @@ concerns about bloat, but this is further discussed in 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 + crate there is no way to group features into sections or have a user-specified layout - Users cannot control features ordering in documentation since the TOML specification defines table keys as unordered. From 4957dd014c902d6b88af4dc9f279fa73ea162b5a Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Tue, 9 Jul 2024 14:06:37 -0400 Subject: [PATCH 07/12] Update text/3485-feature-documentation.md Co-authored-by: Ed Page --- text/3485-feature-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/3485-feature-documentation.md b/text/3485-feature-documentation.md index bf989551d3a..55c4ee30947 100644 --- a/text/3485-feature-documentation.md +++ b/text/3485-feature-documentation.md @@ -21,7 +21,7 @@ Please see the parent meta RFC for background information: [`feature-metadata`]. 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 +gates. Despite 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. From 9cc3334da6f067a3c447735ebb9ed96f4f5e5339 Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Tue, 9 Jul 2024 14:07:17 -0400 Subject: [PATCH 08/12] Update text/3485-feature-documentation.md Co-authored-by: Josh Triplett --- text/3485-feature-documentation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/text/3485-feature-documentation.md b/text/3485-feature-documentation.md index 55c4ee30947..72f669b7ec2 100644 --- a/text/3485-feature-documentation.md +++ b/text/3485-feature-documentation.md @@ -53,8 +53,7 @@ bar = { enables = ["foo"], doc = "simple docstring here"} [features.corge] enables = ["bar", "baz"] doc = """ -# corge - +The first paragraph is a short summary, which might be displayed standalone. This could be a longer description of this feature """ ``` From 9d876951493c43244d4720b01b5caf570c92a379 Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Tue, 9 Jul 2024 14:08:01 -0400 Subject: [PATCH 09/12] Update text/3485-feature-documentation.md Co-authored-by: Ed Page --- text/3485-feature-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/3485-feature-documentation.md b/text/3485-feature-documentation.md index 72f669b7ec2..07517d60445 100644 --- a/text/3485-feature-documentation.md +++ b/text/3485-feature-documentation.md @@ -8,7 +8,7 @@ [summary]: #summary -This RFC describes a new key to under `features` in `Cargo.toml` for +This RFC describes a new key 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). From b6d13a63462ba55593b0114c035dd7413873f7a5 Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Mon, 15 Jul 2024 11:55:22 -0500 Subject: [PATCH 10/12] Add note about rustdoc support of links --- text/3485-feature-documentation.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/text/3485-feature-documentation.md b/text/3485-feature-documentation.md index 07517d60445..6d3e181194d 100644 --- a/text/3485-feature-documentation.md +++ b/text/3485-feature-documentation.md @@ -169,6 +169,11 @@ concerns about bloat, but this is further discussed in [future-possibilities]: #future-possibilities - 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 future, but not at the current time. Users need + to be aware of this potential incompatibility. - 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. From c330adb34e52a5c524ea571a5966224ee35eb950 Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Mon, 15 Jul 2024 11:55:41 -0500 Subject: [PATCH 11/12] Apply formatting --- text/3485-feature-documentation.md | 50 ++++++++++++++++-------------- 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/text/3485-feature-documentation.md b/text/3485-feature-documentation.md index 6d3e181194d..94a601603f8 100644 --- a/text/3485-feature-documentation.md +++ b/text/3485-feature-documentation.md @@ -8,10 +8,10 @@ [summary]: #summary -This RFC describes a new key 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). +This RFC describes a new key 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`]. @@ -33,13 +33,12 @@ for keeping feature definitions and documentation together. [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. The first paragraph -will be treated as a summary, and should be suitable to display -standalone without the rest of the description. +markdown docstring describing the feature. The first paragraph will be treated +as a summary, and should be suitable to display standalone without the rest of +the description. -Don't include the name of the feature in the summary; tools -will typically already display this documentation alongside -the name of the feature. +Don't include the name of the feature in the summary; tools will typically +already display this documentation alongside the name of the feature. ```toml [features] @@ -69,9 +68,9 @@ 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 +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 @@ -92,8 +91,8 @@ crab@rust foobar % cargo add regex 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)* +_(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 @@ -112,18 +111,19 @@ concerns about bloat, but this is further discussed in - 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 into sections or have a - user-specified layout -- Users cannot control features ordering in documentation since the TOML specification defines table keys as unordered. +- Unlike with the + [`document-features`](https://crates.io/crates/document-features) crate there + is no way to group features 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. +- 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` @@ -153,8 +153,10 @@ concerns about bloat, but this is further discussed in - There is an existing crate that uses TOML comments to create a features table: - `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)) + 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 From b2b27a25933e8f3b2561744ef3d6c5fb69b43df6 Mon Sep 17 00:00:00 2001 From: Trevor Gross Date: Mon, 15 Jul 2024 11:58:48 -0500 Subject: [PATCH 12/12] Add an example in the summary --- text/3485-feature-documentation.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/text/3485-feature-documentation.md b/text/3485-feature-documentation.md index 94a601603f8..3a375c76bc2 100644 --- a/text/3485-feature-documentation.md +++ b/text/3485-feature-documentation.md @@ -13,6 +13,14 @@ 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). +Example: + +```toml +[features.serde] +enables = [] +doc = "enable support for serialization and deserialization via serde" +``` + Please see the parent meta RFC for background information: [`feature-metadata`]. # Motivation