Tracking Issue for Rustdoc support of RFC3485 `feature-documentation`

[tgross35]

This is a tracking issue for Rustdoc support of the RFC "feature-documentation" (rust-lang/rfcs#3485).

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.
Discussion comments will get marked as off-topic or deleted.
Repeated discussions on the tracking issue may lead to the tracking issue getting locked.

Steps

• Provide a way for rustdoc to consume this new information
• Display a new feature table in some way
• Add support to rustdoc JSON output
• Adjust documentation (see instructions on rustc-dev-guide)
• Formatting for new syntax has been added to the Style Guide (nightly-style-procedure)
• Stabilization PR (see instructions on rustc-dev-guide)

Unresolved Questions

• Everything!

Implementation history

[tgross35]

Note that this RFC isn't merged yet, but I think a separate place to brainstorm rustdoc support makes sense.

Some ideas about possible UI:

• The features should probably be accessible from the landing page. I was originally thinking somewhere in the left bar would just link to another page:
  

  However, all of those existing links point to anchors on the front page rather than another page, and I'm not sure a feature summary table makes sense (but maybe?).

• There should probably be a single page somewhere documenting all features (along the lines of structs with methods), rather than having a separate page for each feature (like functions or modules).

• The first line of the docs is treated as a summary, like other items, so that can be used if an overview makes sense somewhere

• On the "Cargo Features" page, each feature should get its own name as a heading, and then the doc becomes its content

• We should show feature dependencies in some way (also link them). I don't know how this would look

[GuillaumeGomez]

However, all of those existing links point to anchors on the front page rather than another page, and I'm not sure a feature summary table makes sense (but maybe?).

Actually no, not all of them are anchors. All items isn't, the listed crates aren't either. However, it's not great as it makes it more difficult to find out about them. Might be worth revisiting.

There should probably be a single page somewhere documenting all features (along the lines of structs with methods), rather than having a separate page for each feature (like functions or modules).

Agreed. A features.html file would be great.

The first line of the docs is treated as a summary, like other items, so that can be used if an overview makes sense somewhere

If we have one file containing all features, unless we list the features on the root index.html file (which could also be a good idea), I don't think it'll be needed.

On the "Cargo Features" page, each feature should get its own name as a heading, and then the doc becomes its content

That's how I had it in mind as well. Something close to methods for example for coherency.

We should show feature dependencies in some way (rust-lang/docs.rs#2530). I don't know how this would look

Instead of having the whole dependency tree, I was thinking about showing two things after the documentation:

1. The list of features enabled by this feature directly (so only children, nothing below). Each feature would be a link to an anchor on the same page.
2. If the feature is enabled by other features, have something like "this feature is enabled by the following feature(s):" and then the list of the these features (of which each would be a link once again).