rustdoc should mark #[deprecated] things as such

[SimonSapin]

For example, as of this writing, the StrAllocating::to_owned method is annotated with #[deprecated = "obsolete, use to_string"], but http://doc.rust-lang.org/std/str/trait.StrAllocating.html#method.to_owned gives no indication of that.

[steveklabnik]

👍 for sure

[lilyball]

The documentation now has colored bars indicating the stability status of a given API. There's more work to do though. Here's the issues I see:

• The color bar doesn't tell you what it means when it annotates a function in a function list, like on the linked StrAllocating trait. It only gives the full "deprecated" title when the entire page is about a deprecated item (e.g. native::task::spawn).
• There's no indication in the trait code listing at the top of the page about which items are deprecated, you have to look at the actual function documentation. It would be nice to add the #[deprecated = "..."] attributes into the code listing.
• The deprecated display does not list the deprecation message. This last one I think is the most important.

[lilyball]

cc @aturon, who apparently added the current stability displays in #15263.

Looking at that PR, apparently the deprecation message actually is included, as the title attribute of the color bar. That's rather obscure, I had no way to know that hovering over the bar for long enough would show a tooltip with the message.

[aturon]

I completely agree with @kballard that there's more work to be done on the visual design here.

My focus in #15263 was just getting the information available at all. Now that it's accessible and being rendered within rustdoc, it should be easy to iterate on the design.

That said, it's nontrivial to balance discoverability with noisyness. Adding text like "experimental" for each item would add a lot of noise, now that libstd is almost entirely at experimental status. If someone has a design in mind for striking a good balance, I'd be happy to implement it (or help guide an implementation).

[aturon]

cc #15345

[lilyball]

@aturon For the trait code listing at the top, we should definitely add #[deprecated = ".."] text, because deprecation is important to signal and should be relatively rare. Similarly, in function listings, I think we need a permanent message for deprecation (both to scream "this is deprecated" and to tell the user what the deprecation message is without any interaction).

For other stability attributes, I we can definitely omit them from the code listings, and then I think we can get away with just having mouseover behavior. When I mouse over the function listing, perhaps the stability name could show up right-aligned with some visual treatment.

FWIW, I've advocated in the past for having similar mouseover behavior that exposes a [src] link for every single item. This could coexist with that by either putting the stability attribute to the left of the [src] link, or on a second line below it (if there's room; a function with no documentation may only occupy one line). But we don't currently have mouseover [src] links at all, so we can probably get away with ignoring that.

[steveklabnik]

while #15468 is newer, it's already added to milestones and such, so I'm closing this as a duplicate of that.