Hide unstable items by default in stable rustdoc

[lambda]

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.

[Centril]

This would require either providing an opt-in setting for seeing them

I would prefer this option. One benefit of showing the unstable APIs is that it invites people to test them, so having an opt-in for the curious would be good.

[steveklabnik]

I would prefer an opt-out to an opt-in, that is, keep what we do today, but provide the ability to hide it if desired.

…

On Apr 10, 2019, at 5:21 PM, Mazdak Farrokhzad ***@***.***> wrote: This would require either providing an opt-in setting for seeing them I would prefer this option. One benefit of showing the unstable APIs is that it invites people to test them, so having an opt-in for the curious would be good. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[lambda]

After spending some more time browsing the docs with an eye out for things that are visually distracting or attention grabbing, another option would be to just use a less attention grabbing way to denote unstable and deprecated items.

Right now, they each use an extra, brightly colored box that makes them take up more visual space on the screen than stable items.

On module index pages, they are actually made less prominent; they are sorted to the bottom, and made lower contrast with the background. This helps make them less attention catching, rather than more attention catching. But when browsing the methods provided on a struct or trait, they come with the big bright warning boxes that make them stand out more.

I think I would still have a slight preference for having them hidden by default and just making the nightly docs easier to discover, such as having a version chooser in the header or sidebar, because of the issue mentioned in #31204 about docs of unstable items potentially being out of date. But making them less visually prominent rather than more visually prominent would help a lot.

[jsha]

I agree that the better way to solve this is by (perhaps) reducing the prominence of the "nightly-only" box. I don't think we should hide unstable items in the stable rustdoc generated at https://doc.rust-lang.org/. If someone is reading code that uses an unstable method, there's a good chance they will go to look it up in the stable docs. It would be a frustrating and confusing experience to not be able to find the method in the docs. It's a much better experience to find the method and be informed it's nightly-only / unstable.

We probably don't want to reduce the prominence too much, though. If someone's looking for a method to call, it's pretty important that they notice when it's nightly-only. If they're working on a stable crate, that may mean they're not able to use the method at all.

[jsha]

Candidate PR at #91075