[rustdoc] Add option to hide deprecated items

[FeldrinH]

When looking throught the documentation of a library, I generally want to ignore deprecated items. Some libraries (the standard library in particular) never make breaking changes, so they slowly accumulate a layer of deprecated functions that only adds noise to the documentation when working on greenfield projects.

It would be nice if there was an option to hide deprecated items in the docs.rs documentation.

[Saphereye]

@rustbot claim

[FeldrinH]

Similar to the option to hide deprecated items, it might be nice to have an option to hide unstable items, for when you are working with stable Rust. This is std specific since AFAIK other crates can't define unstable items, but still, would be useful.

[Saphereye]

I also wanted to ask whether it would be better for the deprecated item hiding and unstable item hiding options to be available as command line flags, as options in the settings panel, or both.

Edit: The current PR implements this via a command line flag, but I am leaning more toward providing these as just settings panel options, as I feel that should be an easily togglable feature. I would prefer a second opinion though.

[FeldrinH]

I think settings panel options would be better (if it is technically feasible), then you can use the toggles on docs.rs as well.

[xtqqczze]

As noted in #149551 (comment), this feature was unanimously accepted by rustdoc team members.

[obi1kenobi]

If this option is extended into rustdoc JSON, I'd love to make sure it's an opt-in not opt-out: callers should have to pass a flag to have deprecated items not included in the JSON. The risk is that we'd break cargo-semver-checks' ability to support multiple Rust and rustdoc JSON versions.

The non-breaking way to make it opt-out (which feels like way more work) would be to first add the flag for including deprecated items but make it an no-op initially and keep the deprecated items. Then many Rust versions later (outside the c-s-c version support window), flip the default and make the flag have an effect. That way c-s-c can start passing the flag everywhere to preserve the behavior it needs, even while the default changes. But again, way more work and unclear to me that this effort is worth it.

[xtqqczze]

Actually, it looks like this was already implemented by #151091 for Rust 1.95, therefore this issue can be closed.