Tracking Issue for feature-documentation

[weihanglo]

Summary

RFC: #3485
Original issue: #4956
Implementation: #17447
Documentation: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#feature-documentation

Allow packages to document individual Cargo features in the manifest. Cargo and other tools can use this metadata to display feature descriptions.

Unresolved Issues

• What is the best name for the manifest key? doc was chosen for consistency with #[doc(...)], but package.description and package.documentation (a URL) also exist as precedent.
• How should this be exposed in cargo metadata output?
  One possibility is to extend the existing features entry with a parallel structure:

  "features": {
      "foo": [],
      "bar": ["foo"]
  },
  "features_v2": {
      "foo": {},
      "bar": { "enables": ["foo"], "doc": "simple docstring for bar" }
  }

Future Extensions

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

  foo = { enables = [], doc-file = "features.md#foo" }
  bar = { enables = [], doc-file = "features.md#bar" }

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

[weihanglo]

I am thinking that maybe this can share the same unstable name with #14157, and we stabilize each metadata field separately, keeping the main feature-metadata unstable for new unstable metadata fields.