Feature request: `#[doc(canonical)]`

[jyn514]

I don't have time for a full write-up of this right now, so I'm just opening an issue so I have somewhere to point people when they open rustdoc issues.

Motivation:

• search items are duplicated (rustdoc: do something about reexported items rust#15723)
• rustdoc sometimes links to the original definition, even for facade crates that use inlining: Rustdoc links to std library types can bypass the facade rust#22083
  • ditto, but for intra-doc links: Rustdoc links items in the standard library to the original crate, not the re-export rust#78467 (deemed to be a duplicate of the issue above)
• rustdoc sometimes links to a re-export, even when it is named differently than the link the user wrote: rustdoc: Incorrect link to item when the item is reexported and inlined rust#83976

doc(canonical) could tell rustdoc the 'one true path' the item should appear at.

Possible difficulties:

• doc(canonical) is necessarily unique across all crates. rustdoc should give an error if it's duplicated.
• rustdoc currently stores search-index.json per-crate. This will need a redesign if rustdoc only know to hide the item after the documentation has been generated and it goes onto the next crate

Unresolved questions:

• Does inlining still make sense with doc(canonical)? Should all other usages just link to the canonical crate? How does this work if the canonical usage is in a reverse-dependency?

cc @camelid

[jyn514]

rust-lang/docs.rs#1588 (comment) has a lot of things that are very similar but not the same; I'd love to have a plan for how this affects links to transitive dependencies as well.

[notriddle]

Prior art:

• https://haskell-haddock.readthedocs.io/en/latest/markup.html#hyperlinking-re-exported
• Add a link to the documentation home of a re-exported entity haskell/haddock#14

[jsha]

We discussed this in the 2024-01-08 t-rustdoc meeting and the 2024-03-11 t-rustdoc meeting. To summarize:

This is a useful problem to solve, and we want to solve it, but we're still not sure yet exactly what the solution should look like. Getting concrete, there are two main use cases:

1. facade crates (like std, bevy, to some extent tracing), where canonical path is in the facade crate, or outermost
2. shared types crates (like pki-types, http), where canonical path is in the shared types crate, or innermost

For examples of (2):

• rustls_pki_types::CertificateDer (implementation) vs rustls::pki_types::CertificateDer (re-export for convenience).
• http::Request vs hyper::Request (re-export).

For examples of (1):

• tracing::Event vs tracing_core::Event. But this one is more complicated because the preferred path depends on the use case. Tracing subscribers are expected to depend on tracing-core instead of tracing, while other use cases are more likely to depend on tracing.

Another problem that came up is directionality. A crate that is depended-upon doesn't know about the crates that depend on it. So if, e.g. tracing declared that its version of Event should be canonical, that wouldn't allow tracing-core to do anything differently, because a doc build of tracing-core doesn't know anything about tracing. But also in general the situation for facade crates is probably more complicated than for shared types crates.

I also wrote down what I consider the important use case for a feature like this:

As a user, I am calling a function that returns hyper::Request. I want to know if I can pass that output to a different function that takes http::request::Request as a parameter

One idea that came up towards the end of the meeting was that rather than try to do something complicated with declaring things canonical, we could, when generating inlined re-export docs, add a notation saying "this is a re-export of foo::Bar."

[Lokathor]

A notation to make clear that a re-export happened sounds very good.