rustdoc: Prefixing parent modules to distinguish between items in cases where item names would otherwise be ambiguous

[mitchmindtree]

Motivation

I often run into an issue when reading through rendered documentation where many types exist with the same name and it is unclear which type is being referred to in a function signature or type declaration.

Two simple, common examples of this are the Result and Error types. When displayed within a type declaration or function signature, the reader is unable to tell at a glance what Result or Error type is being referred to, and is forced to either click to the type or hover over the type and examine the link, both of which can be a significant hindrance when reading through large amounts of documentation. Here's an example of an ambiguous error type within a type declaration:

Here, unless you are already familiar with the crate, it is difficult to know exactly what Error type the type declaration refers to, as it is convention for crates (and often sub-modules) to define unique Error types. We can't know for sure without clicking on the Error type and checking exactly which one is being referred to. The same issue applies to ambiguous item names that appear in function signatures and struct fields.

Result and Error are just two examples of many. For example, in math and gaming libraries, the same issues apply to types like Point, Vector and Matrix, and are especially confusing when using e.g. one physics library with one graphics library, or a tessellation library alongside another math library - it is impossible to know for sure exactly what type the documentation refers to without clicking through and interrupting the flow of doc perusal.

Potential Solution

One potential solution that comes to mind might be to prefix these potentially ambiugous types with their parent module in the rendered docs. E.g. in the error case above, the rendered doc might look more like this:

type Fallible<T> = Result<T, failure::Error>;

In this case, we know that there is at least one other type within this crate or its dependencies with the same name (std::io::Error) - in order to remove ambiguity, the Error type is prefixed with its parent module failure, so that it is clear which is being referred to.

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?

---

Just thought I'd share this while it's on my mind in case anyone else has come across a similar desire! I searched past issues briefly but was unable to find this raised elsewhere - feel free to close this in favour of an existing issue if one already exists!

[jyn514]

Duplicate of #74924, but this is a really good write-up! Feel free to post it as a comment on that issue :)