[docs] Attribute to indicate when a function became const

[jhpratt]

Having an attribute like #[doc(const_since("Rust 1.45"))] could be quite useful. It could be similar in appearance to #[doc(cfg(...))], and would likely be similar to implement.

I believe the best design for an API like this would be accepting a string, such that the author could clarify whether it's Rust's version that matters or the crate's version (obviously for stdlib this doesn't matter).

[RalfJung]

Right now, we don't even have an attribute to tell when a function was added at all, right? For the standard library, this is done via #[stable(since=...)], which is part of the unstable staged_api feature. IMO it would make little sense to expose anything like that forconst fn without first exposing it for items in general.

A related feature request would be for rustdoc to actually render the rustc_const_stable information that all stable const fn in the standard library have. That would put const-stability on par with regular stability in terms of documentation.

[jhpratt]

Having when an item was added would also be quite useful. What I've been doing with the time crate is just saying "this function is const fn when using rustc >= 1.x.0", which obviously isn't ideal. It's a similar use case that led to doc_cfg (albeit that is still unstable).

Has the docs team ever considered exposing something along the lines of #[stable(since=...)] to libraries? Off the top of my head I don't believe you're on that team, but it can't hurt to ask 🙂

[RalfJung]

I'm afraid I don't know. I am just saying, I think this issue should be phrased as a general "please expose the 'since' mechanism used in the standard library also to user crates" (aka "stabilize parts of staged_api in one form or another"); the problem is not specific to const fn.

I'll open a separate issue for showing "const-since" information in the standard library (EDIT: that would be #76998).

[jhpratt]

My question is specifically relating to const fn, though. If a user sees that a function is const fn, they could naïvely assume that that was always the case, even if it's not. If they're using an older compiler (even with the latest of the library), the function isn't const fn for them. While the docs would render the correct signature if the user builds the docs themself, I'm fairly certain most people, including myself, default to docs.rs.

You could certainly make an argument that I shouldn't be modifying the signature at all, but I feel that progressive enhancement is best while maintaining MSRV. It's just that there's no clear way on how I should be documenting this.

[RalfJung]

But the exact same thing applies to functions that only exist on sufficiently recent compilers (because older compilers lack some feature they require). I see nothing specific to const-fn here, so I don't see why the solution would be const-fn-specific.

[jhpratt]

While true, I don't personally see a use-case where a function wouldn't exist on older compilers — the crate author is more likely to shim functionality or bump MSRV. But I see your view point.

[jyn514]

I think this is a duplicate of #79663.

[jhpratt]

Coming back around to some issues that I created a long time ago. While not strictly a duplicate of #79663 (an attribute could be added without full stability capabilities), I think that issue is the best way forward on this issue. Closing for that reason.