Add support for `#[doc(since="version")]` attribute

[dodomorandi]

To the present day, the internal crates like core and std can annotate things with #[stable(since="version")]. This is extremely useful for users, especially because rustdoc is able to write this information in the rendered documentation.

Unfortunately, this kind of feature is not available for normal crates. Take, for instance, tokio::runtime::Handle::current: this function is available since version 0.2.8 of the tokio crate (not sure about 0.2.7, that's not the point), but this information is not available at a first glimpse.

IMHO, adding the possibility of annotating functions, structs and traits (and maybe something I missed) with #[doc(since="version")] would give more doc power to crates' authors. Moreover, it should be possible to leverage the current implementation of stable(since="version") in order to introduce the feature without reinventing the wheel.

[GuillaumeGomez]

We had been asked about it in the past too but it got rejected at that time. However I am very favorable to this add.

[jyn514]

This is a duplicate of #74182 (created earlier, but with less discussion).

[dodomorandi]

@jyn514 Sorry, I think you posted the wrong duplicated issue, because it is just this one 😄

[jyn514]

Oh oops, thanks! I meant to link to #79663.

[emilyalbini]

I don't think this is the same feature as #79663: that issue is about having a way to mark items as unstable, while this is just to add a "since 1.2.3" near the function signature.

[jyn514]

@pietroalbini staged_api does both those things. I guess it depends whether you count #79663 as a request to stabilize all of staged_api or just deprecations.

[emilyalbini]

I think it's better to keep this and staged_api separate.

Stabilizing #[unstable(...)] sounds a lot more complex than this issue (would that mean #![feature()] for crates too? which channels can use crate unstable features? how does that interact with api stability?), while this issue just proposes adding a way to annotate functions on rustdoc with the version number they were introduced in.

[Cldfire]

It could be neat for this attribute to support linking to the changelog for the version specified (inspired by the Rust Search Extension):

Image

This would probably require a way to globally specify a root changelog URL for a given crate.

[archer-321]

In addition to being useful as a hint in the rendered API documentation, this annotation could be helpful for tools in automatically detecting minimal dependency versions. Even if not all of a library is annotated, tools would know they can start testing with "at least version X".

Testing whether a using crate still compiles with some version obviously doesn't catch all kinds of breaking changes in an API, so unless the entire API is annotated with this attribute, automatic minimal dependency version detection would never be reliable. However, this attribute still allows for an "educated guess" in those cases.

[jyn514]

Major new features like this should have an RFC IMO.