Hide unstable items by default in stable rustdoc · Issue #59853 · rust-lang/rust (original) (raw)

Right now, the docs produced on the stable and beta channels include unstable items. The docs are already fairly complex and contain a lot of information to sort through, and finding documentation for items that are not usable for the majority of developers working on stable Rust does not help with this. In addition, unstable APIs have very attention-grabbing warnings associated with them, making them much more prominent than the APIs that are actually usable.

This has been broken out of #59829 to provide smaller, actionable items that can be independently discussed and worked on. A review of rustdoc for accessibility, especially for dyslexia and attention disorders, finds that there are a number of visually distracting elements in rustdoc which can draw attention away from the main content. This should be considered along with the other issues mentioned in #59829 about the overall effect of a number of distracting elements on the page.

This has been previously discussed and closed in #25863 and #31156. However, when it was first discussed was very shortly after the Rust 1.0 release, when there was a large amount of API surface which had not been stabilized for the 1.0 release, and what could be done with stable Rust was fairly limited (for example, no stable proc macros so Serde was only usable on nightly Rust).

At this point, most people can use stable Rust for most tasks. There is a lot less reason for the average Rust developer to need to switch to nightly to use unstable standard library features.

There is also the open issue #31204 that the stable docs of unstable items may be out of date; because these items are unstable, they can change in nightly releases, so not only are they a distraction, but they may be misleading for people who actually try to use them.

Between the extra information that most people don't need, distracting UI, potential for being out of date, and time since this was last discussed, I think that it is worth reconsidering this decision and hiding unstable items in the stable docs by default.

This would require either providing an opt-in setting for seeing them, or make finding the nightly docs easier.

An alternative discussed in the comments is to just make them less visually prominent; unstable items are already rendered at lower contrast and at the bottom on module index pages, but within struct or trait documentation they have big bright warning boxes calling attention to them. Making them less visually prominent, such as by reducing their contrast and making the warning just plain unstyled text, perhaps in the same place that stability information goes (though see #59851 for discussion on that), would help out a lot.