Rustdoc: indicate deprecated items on the sidebar

[tgross35]

For example, at this link: https://doc.rust-lang.org/std/macro.try.html

try is deprecated but there's no way to easily identify that from the sidebar. Adding a deprecated label there (or the thumbs down emoji if space is a concern) would be quite helpful.

Sorting deprecated items to the bottom would also be quite reasonable imho, to avoid noise for anyone looking for only non-deprecated methods. (This probably wouldn't be bad to do for deprecated methods as well on the main page, since the ordering is a bit random. But that's a separate discussion.)

@rustbot label A-rustdoc-ui C-enhancement T-rustdoc

[tgross35]

Zulip thread: https://rust-lang.zulipchat.com/#narrow/stream/219381-t-libs/topic/Deprecation.20of.20std.3A.3Au32.20shells

[jsha]

I think sorting to the bottom would be a bad idea because it violates the typical behavior that the list of methods is sorted alphabetically, and is hard to explain concisely. When people read documentation, it's not only to discover new methods that they might use. It's also to discover the meaning of a method that they saw used in existing code. We shouldn't make a method harder to find just because it's deprecated.

Given the restricted space in the sidebar, I think it's reasonable to require clicking on the item before seeing that it's deprecated. After all, there's no risk that someone will see try in the sidebar and immediately try to use it without reading the documentation. Because without reading the documentation how would you know which arguments to pass it?

[tgross35]

Good point about the alphabetical sorting, I guess moving them to the bottom isn't needed.

I still think a deprecated or smaller dep. flag would be good, since I see deprecation as quite different from function signatures. It's less about "does this function suit my needs" that you might expect to find in the signature, and more about "should I consider using this function at all". Which doesn't matter when you're trying to understand existing code as in your example, but does matter when you're creating new code.

Having a flag just allows a bit of visual filtering that isn't otherwise available when you're searching for a method. You can kind of guess what a function signature looks like from the name (try_ indicates failable, _with indicates a closure, and the name itself is usually a good description), but there's no equivalent for deprecation. Having a dep. flag would just make it easy to quickly prune off completely useless items from your search.

[GuillaumeGomez]

I agree with @jsha: the space in the sidebar is very limited so adding new information would need to be very space efficient.

[tgross35]

Just for a rough idea, this is about what I had in mind:

I kind of also like the single letter option. It's better with space and could be used to indicate nightly as well - not that I think this is needed as much as something to indicate deprecation.

Just a<span title="" class="stab deprecated sb-flag">Dep.</span> with:

.sb-flag {
	padding: 2.5px;
	margin-bottom: 3px;
	font-size: 0.82rem;
	margin-left: 5px;
}

[GuillaumeGomez]

As soon as the item is too long (where the "..." appears), this wouldn't work anymore. What I had in mind was actually to use the space on the left. But I'm really not sure it's a good idea.

[jsha]

I still don't think this is a good idea. The purpose of the sidebar is skimming for an item name and jumping to it. Any decoration other than the item name slows down that process, and actually draws more attention to the decorated items. It's okay to discover that an item is deprecated by clicking on it.

[Jules-Bertholet]

Another option is to have deprecated items use a different text color in the sidebar ("grayed out"). That way the space used doesn't increase.