rustdoc: disambiguate between types of the same name

[QuietMisdreavus]

As an extension to #38414 and #39589, any hyperlinked reference to some type should be checked against everything within that crate - within any dependent crate too, if possible. This will help clear the confusion between the perennial problem types in std, std::result::Result and std::io::Result (and to a lesser extent, std::io::Write and std::fmt::Write).

Some before/after screenshots made with chrome's inspector with what I have in mind:

[ollie27]

Related to #34999.

[GuillaumeGomez]

I just wonder: should we add the path only when the item is present more than once or should we do it everytime?

[QuietMisdreavus]

As in, print the full path regardless of whether it shares its short-name with anything? I suppose that could work. It'd certainly be easier to implement, though it risks being overly verbose.

[GuillaumeGomez]

That's my main concern.

[QuietMisdreavus]

Looks like this is a more general version of #16096.

[jpetkau]

Always printing the full path would make the docs vastly more useful for me. Even if a name isn't reused, it's still important to see where it's actually coming from.

But for reused names this is really important, since re-using the same name in many related crates is common practice. (E.g. today I was trying to figure something out with bincode, and ended up on https://docs.rs/bincode/1.0.0-alpha7/bincode/type.Serializer.html. The doc reads:

type Serializer = Serializer<W, LittleEndian>;

This is not useful at all. Clicking on the last Serializer takes one to bincode::endian_choice::Serializer, which is not correct; it's actually referring to serde::Serializer. Even if the link was correct, though, this line is just meaningless without knowing what the names resolve to.

[mitchmindtree]

@jyn514 mentioned it might be worth posting my OP at #65330 (a duplicate issue) to the main discussion here, but it looks like a lot of my points have already been covered here so I'll just leave it at a link.

should we add the path only when the item is present more than once or should we do it everytime?

My personal preference would be to prepend the parent modules until there can no longer be any ambiguity to which type is referred to. The paths to some types can get incredibly long. If the full path didn't help to disambiguate the type, I imagine it might just appear a bit noisy.

From #65330,

Keeping in mind I am unfamiliar with rustdoc internals, I wonder if this can be achieved by keeping a map from item names to whether or not they occur more than once during the documentation process. For all items that occur more than once in the crate or its dependency graph, their parent modules are prefixed to the item name until the ambiguity is resolved?

[jyn514]

keeping a map from item names to whether or not they occur more than once during the documentation process

I think it should be per-page, not for the whole crate. Otherwise you'd get lots of false positives from dependencies when you really are interested in disambiguating the current page.