rustdoc picks an odd "canonical" path for some often-reexported types

[RalfJung]

It seems that recently, rustdoc started to not show duplicate results for a type when it gets reexported. That is great! However, the name it decides to pick is sometimes odd.

Consider for instance InterpError: rustdoc shows this as miri::InterpError, which makes it look like a type defined in Miri. That's not the case though, the type is defined in rustc_middle. I would have expected this to be shown as rustc_middle::mir::interpret::InterpError -- that's the canonical path for this type, as far as I am concerned. Certainly it should be showing some rustc crate as otherwise one could easily think that this type is not available outside Miri.

Cc @rust-lang/rustdoc

[notriddle]

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)]

[RalfJung]

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

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

[RalfJung]

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.

[fmease]

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”).

[RalfJung]

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?

[fmease]

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.

[notriddle]

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).