rustdoc picks an odd "canonical" path for some often-reexported types about rust HOT 8 OPEN

Ah, I see. Thanks for the explanation. Sorry for spreading misinformation before.

from rust.

I think this needs solved using rust-lang/rfcs#3011. The behavior you’re seeing here is the same as the behavior in the standard library (except we actually want it in that context), combined with Search preferring shorter paths.

If you want a workaround for right now, mark the re-export as #[doc(no_inline)]

from rust.

If you want a workaround for right now, mark the re-export as #[doc(no_inline)]

Ah, that's what that attribute does. :D

from rust.

The behavior you’re seeing here is the same as the behavior in the standard library (except we actually want it in that context), combined with Search preferring shorter paths.

The standard library feels special, in that we often want to use the std items even when they exist in core/alloc. For a collection of crates like rustc, that's not the case -- doesn't one often want to avoid re-exports there?

In the end, the best path to use depends on where in rustc one is working. Maybe the page for InterpError should list that this is available as rustc_middle::mir::interpret::InterpError, rustc_const_eval::interpret::InterpError, and miri::InterpError -- i.e., for each crate that re-exports this, show the nicest (shortest?) path in that crate.

from rust.

Edit: Please check out #124608 (comment) first. While the user-facing behavior described below can be reproduced as described, my attempt at an explanation is incorrect.

Consider for instance InterpError: rustdoc shows this as miri::InterpError

Just to give more context to future readers: The exact outcome depends on the “current location”, i.e. which crate you are currently viewing.

If you follow the link https://doc.rust-lang.org/nightly/nightly-rustc, the current crate will be rustdoc at the time of writing because bootstrap documents it last. miri gets documented before that but obviously after rustc_middle. Therefore and for the reasons mentioned by notriddle, it's miri::InterpError that gets returned by search.

However, if you navigate to the index page of crate rustc_middle and search for InterpError again, the search result will be rustc_middle::mir::interpret::InterpError because the docs of rustc_middle get generated before miri (as mentioned) and they can't “see into the future” / reference items yet to be generated from its point of view (and search doesn't seem to be “global”).

from rust.

Ah, interesting, I had no idea the result would differ depending on the crate.

But I supposed if I use the rustc_middle crate page then items defined "later" just cannot be found at all, right?

from rust.

if I use the rustc_middle crate page then items defined "later" just cannot be found at all, right?

Actually those items can be found contrary to the re-exports (just tested it). I don't know why there exists this discrepancy as I'm not super familiar with rustdoc search, @notriddle is the expert here.

from rust.

the search result will be rustc_middle::mir::interpret::InterpError because the docs of rustc_middle get generated before miri (as mentioned) and they can't “see into the future” / reference items yet to be generated from its point of view (and search doesn't seem to be “global”).

Actually those items can be found contrary to the re-exports (just tested it). I don't know why there exists this discrepancy as I'm not super familiar with rustdoc search, @notriddle is the expert here.

Rustdoc Search generates a single search index file that contains items for all crates that have been documented together, and every page in a set of docs loads the same index. When more docs are added to an existing set, the rustdoc compiler merges the new items into the existing index file.

The current crate is given higher ranking in the search results, but that's a mere ranking signal, not a necessary side-effect of the way it's built. If it's a usability problem, it can be removed.

It's more complicated for the plain HTML pages, which aren't as easy to merge as JSON files (especially since the search index was designed to be easy to merge this way).

from rust.