Hide unstable items in beta/stable documentation?

[SimonSapin]

I can’t find the link to this anymore, but I remember a user saying the seeing unstable methods and other items in the documentation felt like teasing, since they can’t be used in stable Rust.

Indeed, since they’re impossible to use, unstable items are effectively not there when you’re using the stable or beta channel. Should their documentation be removed entirely from https://doc.rust-lang.org/stable/std/ https://doc.rust-lang.org/beta/std/ ?

I think this could be done by having rustdoc consider that #[unstable] implies #[doc(hidden)] when option_env!("CFG_DISABLE_UNSTABLE_FEATURES").is_some().

CC @steveklabnik

[alexcrichton]

It is currently an explicit decision to not hide these kinds of items in the documentation. It means that generating the documentation among the three release channels is much easier and more consistent, and it also gives you an idea of what's up and coming. We don't want to hide all unstable APIs 100% from everyone because much of the point of a nightly channel is to have users test the APIs before they're stabilized. Most users only browse the stable docs, so hiding all unstable APIs means that it's that much harder to discover.

I personally found that we had so few unstable APIs in the normal stable API surface areas that it wasn't noisy at all to see unstable APIs. If a documentation page is mostly unstable, then it means we should either remove or look to stabilizing the module. Most pages should have at most one or two unstable items.

[steveklabnik]

Yes, what @alexcrichton said.

[SimonSapin]

I didn’t know this was an explicit decision, and the reasons sound good.