doc request: stable doc pages should link to nightly docs for nightly-only features

[pnkfelix]

Today I was trying to puzzle out why I was getting this error:

error[E0223]: ambiguous associated type
   --> src/lit/src/grid.rs:106:13
    |
106 |             RangeInclusive::Empty { at } => PtRangeIterator {
    |             ^^^^^^^^^^^^^^^^^^^^^ ambiguous associated type
    |
    = note: specify the type using the syntax `<std::ops::RangeInclusive<_> as Trait>::Empty`

error[E0223]: ambiguous associated type
   --> src/lit/src/grid.rs:112:13
    |
112 |             RangeInclusive::NonEmpty { start, end } => PtRangeIterator {
    |             ^^^^^^^^^^^^^^^^^^^^^^^^ ambiguous associated type
    |
    = note: specify the type using the syntax `<std::ops::RangeInclusive<_> as Trait>::NonEmpty`

Googling for "rust std::ops::RangeInclusive" sent me here:

https://doc.rust-lang.org/std/ops/enum.RangeInclusive.html

and I kept staring at this definition, saying "why is rustc complaining about my use of this enum?"

I briefly wondered if maybe I was looking at an outdated version of the docs, but the url seemed official, and the page even said "This is a nightly-only experimental API.", which made me say "okay these docs even know that this type is for nightly-use only, so this must reflect what the nightly compiler is seeing."

However, my reasoning there was completely bogus.

Those doc pages above are for the last stable release. Which does not reflect changes that have happened to the nightly compiler, even though they are advertising stdlib types that are only available in nightly (and thus may have diverged from the given documentation).

The url I should have wanted is:

https://doc.rust-lang.org/nightly/std/ops/struct.RangeInclusive.html

So, my thought:

Should features available solely in the nightly compiler either be filtered out from the stable docs, or, alternatively, should they include a link to the nightly docs?

(Adding such a link automatically may be tricky in a case like this, where the embedded within the two urls is the distinction between whether RangeInclusive is an enum or struct. But maybe we would just implement this forward link within the #[unstable] attribute, where it could be manually adjusted to reflect such changes?)

---

(Unfortunately, revising my google search to: "rust nightly std::ops::RangeInclusive" still has the same (stable docs) url as the first result; the nightly docs come up second there.)

[GuillaumeGomez]

It seems a bit problematic to add such a feature because there is rarely both nightly and stable version of a doc generated. Also, it'd force rustdoc to have an implementation strongly dependent on how rust-lang.org is working. I think it's not something we might want.

cc @rust-lang/docs
cc @rust-lang/dev-tools

[QuietMisdreavus]

In the past, the reasoning behind keeping unstable items in stable documentation has been to build interest for participating in their stabilization. Stripping unstable items from documentation is likely to be denied for this reason.

The issue with trying to link forward is that the rendering of a set of docs is dependent on how the source code looks when a release is cut for beta, plus any backports that occur during its beta cycle. Even if we change the #[unstable] attribute to link to the proper documentation, syncing this change forward requires us to backport every structural change that occurs to unstable items to beta, just to update their documentation. My assumption is that beta backports are supposed to be kept few and far between, so I doubt that will fly, either.

There has been discussion in the past with putting a version switcher in the major stable/beta/nightly docs (rust-lang/rfcs#1826), which could help somewhat, though in this specific case you'd either be caught with a broken link (for being changed from an enum to a struct), or just routed to the root docs if it's not written to direct to the same page you're on. I think having that version switcher would have helped the most, so you could quickly notice you were working on the docs for stable, rather than nightly.

[steveklabnik]

A major change like this is RFC territory, IMO.

[steveklabnik]

Update: yup, this is a major change, and so needs an RFC. Closing in favor of that!