Clearly note that unstable items in stable docs may be out of date

[lifthrasiir]

People seems to use the stable documentation to look for unstable items that are not available in the stable nevertheless. As per #25863 it is intentional, but then there remains a tough case of out-of-date documentation. In the IRC I have heard of one such example that the clone_from_slice method used to accept different slice lengths but since then updated to panic in such cases.

We cannot regenerate the stable documentation every time nightly updates, but we can probably link to the unstable documentation as the best effort. Something like this:

[steveklabnik]

This also won't universally work, as sometimes, unstable features are removed and renamed. 👎 from me.

[lifthrasiir]

@steveklabnik You are right. But you can instead link to the search page as an alternative. Frankly, even the notice that it might not be current would be helpful; it is just an idea, after all.

[ollie27]

What about just removing unstable items from stable docs? I've never understood why they're included because they're always out of date as shown here and add unnecessary noise.

[rphmeier]

@ollie27 That seems reasonable to me. It's not as if you can use unstable features from stable. I suppose the purpose is to inform users that they may have a solution if they are willing to use nightly, but it might create more confusion than it's worth.

[steveklabnik]

We kept them in specifically so that you could see that something may be
added in the future and get involved in the conversation if the feature
matters to you.

On Tue, Jan 26, 2016 at 11:44 AM, Robert Habermeier <
notifications@github.com> wrote:

@ollie27 https://github.com/ollie27 That seems reasonable to me. It's
not as if you can use unstable features from stable. I suppose the purpose
is to inform users that they may have a solution if they are willing to use
nightly, but it might create more confusion than it's worth.

—
Reply to this email directly or view it on GitHub
#31204 (comment).

[steveklabnik]

Triage: no changes. Due to the stuff in my previous comments, I still think this is a bad idea, but I'll let @rust-lang/rustdoc decide that.

[GuillaumeGomez]

I also think this is a bad idea. It can't be applied generally on the std lib.

[QuietMisdreavus]

I generally agree with @steveklabnik and @GuillaumeGomez. It's not worth trying to add mapping information if an unstable item is moved, renamed, or deleted, since the stable docs are generated once, upon release, and never touched afterward. Attempting to add this mapping information would result in noisy backports that only serve to provide information for something that's not useful to stable users anyway.

However, there may be a way to salvage the issue, if we don't have to link to the actual item. Would it suffice to add a generic note like "Please note the item may be different on the [nightly docs]," where the link points to the root of the nightly docs, instead of the item itself? That would be much easier to add.