Don't pollute docs/suggestions with libstd deps

[alexcrichton]

Currently dependency crates of the standard library can sometimes leak
into error messages such as when traits to import are suggested.
Additionally they can leak into documentation such as in the list of
"all traits implemented by u32". The dependencies of the standard
library, however, are intended to be private.

The dependencies of the standard library can't actually be stabl-y
imported nor is the documentation that relevant since you can't import
them on stable either. This commit updates both the compiler and rustdoc
to ignore unstable traits in these two scenarios.

Specifically the suggestion for traits to import ignore unstable traits,
and similarly the list of traits implemented by a type excludes unstable
traits.

This commit is extracted from #73441 where the addition of some new
dependencies to the standard library was showed to leak into various
error messages and documentation. The intention here is to go ahead and
land these changes ahead of that since it will likely take some time to
land.

[rust-highfive]

r? @GuillaumeGomez

(rust_highfive has picked a reviewer for you, use r? to override)

[tesuji]

r? @estebank

[GuillaumeGomez]

Don't you want to filter them out only on non-nightly builds?

[alexcrichton]

I don't think so because that still creates the same issues seen on #73441 where it causes broken links to appear in libstd's nightly documentation because libstd's internal dependencies aren't documented.

[Mark-Simulacrum]

@bors try

I would like to make sure that this doesn't affect the published rustc docs -- all of those are currently marked unstable, but we do indeed want to display e.g. the HashStable impl on the Symbol page: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/symbol/struct.Symbol.html#impl-HashStable%3CCTX%3E

I think the current state of this PR will not do so; it might be preferable to limit the exclusion to apply to just std + core + alloc perhaps. I'm not sure if that's the best approach, though. Maybe we should be (for example) annotating these dependencies with #[doc(hidden)] and some rustc attribute (#[rustc_never_suggest]) and making those do the right thing for this case.

[bors]

⌛ Trying commit fde8d11 with merge 9ffb7801363cff45dcb56fa2146a48aa0ae433db...

[bors]

☀️ Try build successful - checks-actions, checks-azure
Build commit: 9ffb7801363cff45dcb56fa2146a48aa0ae433db (9ffb7801363cff45dcb56fa2146a48aa0ae433db)

[alexcrichton]

The intention here, to clarify, is that there are crates whose source code we do not control (e.g. gimli) which are going to become dependencies of the standard library. The problem is that rustdoc, under "traits i32 implements", listed impl GimliPrivateTrait for i32. Additionally when you did something like 0i32.gimli_private_method() rustc would say "oh did you mean to import gimli::GimliPrivateTrait"? (the latter didn't practically happen, but it happens when gimli_private_method is actually named something like read)

The intention here is that libstd would get all its documentation, although rustc is a good point I forgot to consider. Again to clarify though the heuristic isn't to avoid documenting things, it's just to skip listing foreign unstable traits under "traits implemented" in rustdoc (otherwise broken links are generated). Checking the rustc docs there's lots of impls and such for HashStable, including Symbol.

I do suspect that docs are lacking in a way I'm missing though. One example I've found is that Option<T> and Result<T> no longer list that they implement the Try trait when rendered into the libstd docs. When you look at the libcore docs, however, then you can see the Try implementation.

If this is crucial to keep implemented I could try and add some sort of check where only std, core, alloc, and rustc_* can have unstable trait impls imported from them. Or I guess we could try to rename the unstable feature for libstd deps and have a different unstable feature for rustc? I don't really have a great solution.

[Mark-Simulacrum]

Yeah, I think keeping Try in docs is probably pretty important -- I'm not too worried about rustc docs, I think, but std docs missing public traits is pretty unfortunate.

I don't have any strong feelings on this though, and I do think the backtrace work is probably more important than figuring this out, I'd personally be fine landing this as-is (even with the slight regressions) -- realistically, unstable traits aren't that important.

We can also "fix" the rustc case by avoiding passing -Zforce-unstable-if-unmarked or w/e the flag is when documenting rustc, I think.

[ollie27]

rustdoc has a #[doc(masked)] attribute for this issue. Adding #[doc(masked)] extern crate gimli; lines to std for all of the dependencies should fix the docs part of this.

[alexcrichton]

@ollie27 this is a problem not only for direct dependencies but also transitive dependencies of the standard library. For example libstd does not actually depend directly on gimli, it's transitively through other crates gimli is pulled in.

[estebank]

r=me on the diagnostic affecting changes, but feel free to continue the conversation around rustdoc

[ollie27]

@ollie27 this is a problem not only for direct dependencies but also transitive dependencies of the standard library. For example libstd does not actually depend directly on gimli, it's transitively through other crates gimli is pulled in.

Is there any reason gimli can't be added a dependency to std in order to add #[doc(masked)]? It's not pretty but it's the current mechanism to handle this.

[alexcrichton]

At this point it's already hard enough to add dependencies to the standard library and this is a hidden gotcha that seems very difficult to remember. I would much rather have a systematic solution that fixes the problem for all dependencies instead of just one at a time as it just so happens to be an issue. The list of crates that this needs to apply to are:

• cfg-if
• compiler-builtins
• gimli
• rustc-std-workspace-*
• object
• miniz_oxide
• adler
• hashbrown
• libc
• addr2line
• unwind
• panic_unwind
• panic_abort

This isn't just a trivial list of dependencies, and this list is going to be difficult to manage over time. I'm not sure why we'd want to put ourselves through those paces rather than just fixing this once.

[Mark-Simulacrum]

I am actually fairly surprised that rustdoc is listing trait impls for dependencies of std. Maybe it would be sufficient to just not document gimli etc (instead only a specific list, probably core/std/alloc only) in bootstrap?

[alexcrichton]

The gimli crate is not documented, the problem is that rustdoc is listing ReaderOffset for u32 under "traits implemented for u32 on the u32 primitive page. The trait itself is not linked (it's just text), but one of the methods on that trait has a "Read more" link which is a dead link. This is what fails the link checker.

Showing impl ReaderOffset for u32 on the page isn't really needed anyway (although it's drowned out by hundreds of other impls).

All that basically to say that gimli is already not documented. This'd probably actually be fixed if it were since the link would be generated correctly.

[Mark-Simulacrum]

Huh, so rustdoc is finding out about the trait impl some other way. I am personally inclined to land the PR in its current form -- we do lose Try impls and (presumably) some others like SliceConcatExt and so forth, but that seems largely fine. I also don't think we have a good handle on an "excellent" fix beyond the one this PR takes on.

In the long term, I suppose that rustdoc would receive information from Cargo about public/private dependencies and based on that show (or not show) trait impls on types.

[ollie27]

One option would be to invert #[doc(masked)], i.e. mask every crate that doesn't have a special attribute applied. That way std would only need to add an attribute for core and alloc.

Another option would be to tell rustdoc to hide anything from crates it can't generate local relative links to when documenting std. That would have the same effect.

Long term I wonder if #44663 could be used to resolve this.

I guess we can merge this temporarily if it helps unblock things though.

The trait itself is not linked (it's just text), but one of the methods on that trait has a "Read more" link which is a dead link.

That's very much a rustdoc bug, I've filed #74222.

[alexcrichton]

FWIW these all do indeed sound like other alternatives to this, although they do all seem like more work than this local fix. This'll be required for #73441 but that's still waiting on review so it's not necessarily super urgent to fix this now but I suspect #73441 will be ready in the near-ish future.

[alexcrichton]

So to clarify, it this still waiting for someone to take a look? Is it expected that I'm to take action and implement a different strategy other than this PR?

[Mark-Simulacrum]

I believe either @GuillaumeGomez or @ollie27 need to decide whether they're okay with landing this patch as-is (@estebank has approved the diagnostics changes). I myself am fine with it as is, if not super happy, but I think it's good enough. I don't feel comfortable approving if there's outstanding objections on their ends though.

[GuillaumeGomez]

I guess this is an acceptable fix for the meantime but please open an issue so we can write a full one later on. So unless @ollie27 has objections, r=me.

[alexcrichton]

@ollie27 could you weigh in on the latest comments?

[ollie27]

If this is holding up other work and people are okay with the docs regression especially with the compiler docs then I'm not going to block this.

@bors r=estebank,GuillaumeGomez

[bors]

📌 Commit fde8d11 has been approved by estebank,GuillaumeGomez

[Manishearth]

Note: this caused a regression, see #74531