The standard problem with this is ensuring that all crates have a common vocabulary of standard types, like Option and Result.
If we were going to version std, we would need to handle that, such as by re-exporting all the types that didn't change. And at that point, we might just want to keep it as one common crate and add new types, possibly migrating the names over an edition.
Just see the URLs: https://doc.rust-lang.org/nightly/core/ implies nightly. https://doc.rust-lang.org/beta/core/ implies beta. Why would https://doc.rust-lang.org/core/ then not imply stable, that is, stable only? Otherwise why have different sets of documentation at all?
Even more so: https://doc.rust-lang.org/stable/std/clone/trait.UseCloned.html has stable in the name, 1.91.0 (or whatever current) stable version and its timestamp in the top left, so it should obviously be "stable" - but it is not.
https://doc.rust-lang.org/std/clone/trait.UseCloned.html shows the same, except for the current nightly version in the top left.
Not exactly. Yes so for us posting on Internals, and those who are willing to use nightly - but those already know about https://doc.rust-lang.org/nightly/. General Rust users or docs readers are not interested in nightly. If everyone were using nightly, would we need stable?
If that is questionable, shouldn't we ask general rust users (like in the annual questionnaire)? This is not a language expert's decision, nor an API expert's decision. This is about documentation - shouldn't it be the readers' decision?
If the goal is to minimize suggestions duplicating nightly features, that's easy: In GitHub issues template have a link to nightly documentation and a checkbox that the user searched there for anything related. We could even have a bot that would
nightly docs.This doesn't mean that, as-is
nightly features (especially ones that are not on beta) are suitable for general public,nightly "space" (not features, but the space, more below) becomes better, it doesn't mean that stable docs should include nightly features. As per above.The nightly "space" is a pain even for someone used to navigating through it. Rust GitHub Issues/RFC/Docs "governance" (not the Foundation, but, simply, people in charge of tickets/docs/pull requests) have not been keeping it up to par for inviting more people to use nightly. This feedback is mostly for nightly language features, which, understandably, take much longer (if at all) to stabilize (compared to nightly core/alloc/std API), have much fewer potential contributors and are more difficult to test. The painful pattern: GitHub tracking issues, RFC's, feature names (ones used in #[feature(...)]) "get" out of date, even for months (tracking issue Tracking Issue for RFC 213: Default Type Parameter Fallback · Issue #27336 · rust-lang/rust · GitHub incorrectly closed for 8 months in the past). Const Generics didn't have any code documentation (even in its RFC), not even workable examples, even after it was stabilized...
Of course, contributors/people responsible get overloaded, tired, have jobs, or just want/are needed to work on the next "exciting thing". And for many of them, we do want them on that next exciting thing. Yes, their lives are too short.
But, there must be ways for the Rust community to do better. Could Rust Foundation pay for what some parliaments call "whips" to do the "boring"/admin tasks? Or could we have some bureaucracy-earned merits, where bors (or some other bot) removes privileges if a person doesn't perform a certain % of tasks as admin/cleanup/docs/followup/tracking... tasks (except for people in high demand).
I use nightly most of the time (that's why I didn't notice the "unstable-on-stable" docs problem before). And I'm all for wider/granular nightly-beta-stable spectrum.
However, again, Rust GitHub Issues/RFC/Docs... "governance" is not up to par. And even if it were, a natural consequence would be to want to have more granular control of where nightly can, or rather can NOT, be used. But look at how much opposition: Allow setting RUSTC_BOOTSTRAP=1 on specific crates....
I find it quite useful that the stable docs have unstable APIs, since I can easily make a link to a particular version of the API by using e.g. https://doc.rust-lang.org/1.69.0/std/sync/struct.OnceLock.html whereas if I linked to nightly the link points to whatever the latest version happens to have there rather than a specific version.
Because stable is a different branch from beta and nightly. stable gets updated only on stable releases, nightly gets updated every night.
Could there be an option in the settings to hide the unstable stuff?
That was a rethorical question. Of course I know a difference between stable and nightly.
But, as-is, "stable" API documentation ignores that and shows nightly API. Which is confusing to people, because, simply, implying that stable and nightly is the same is a lie. Our lives are too short.
They are explicitly marked as nightly-only. So I can't see how there is any implication that nightly and stable are the same.
There is a big blue banner stating that they are nightly only (usually with a link to the tracking issue), and on modules pages there is an Experimental tag next to the name.
What more do you think would be needed?
The top left states "stable".