Consider warning when intra-doc links fail on a cross-crate re-export

[jyn514]

This is the exact opposite of #56922 😆

There have been a lot of silent failures popping up WRT cross-crate re-exports (#77193, #75855, #76106), and they're hard to notice because the failure is completely swallowed, you have to manually inspect the generated docs.

The rationale in #56922 was that

Since the downstream crate has no way to fix the resolution failure in the upstream crate, it shouldn't be reported, much like capping lints.

This is only true if the failure existed in the upstream crate. If it only appears on the re-export, it will fail completely silently for both the original crate and the current one. This is especially bad when you're adding additional docs on the re-export:

/// [broken_link]
pub use std::string::String;

It could also appear for things outside of the control of the new crate, though: #75855

I think it also makes sense to warn for rustdoc bugs, since otherwise the user never knows to report them and we can't fix them.

@rust-lang/rustdoc what do you think?

cc @euclio

[jyn514]

See also my write-up in #77193 (comment): possibly we could make [broken_link] warn while still hiding failures from the original crate (although I'm not sure how). That still wouldn't catch rustdoc bugs, though.

[GuillaumeGomez]

If your crate reexports an item, the reexport itself is part of your crate, so if there is a broken link in the documentation you added on it, we should definitely emit a warning.

[dhardy]

cargo-deadlinks does report the broken link. I guess that tool should be obsolete now maybe?

Is it not possible to just resolve the issue by considering links in doc inherited via a re-export as being relative to the crate it was defined in? E.g. the doc in rand::distributions::Uniform references Rng (rand::Rng), which does not exist in rand_distr, causing an error when the doc on re-export rand_distr::Uniform is checked. But if rand_distr::Rng did exist allowing the link to be resolved, it would be wrong (if this was not also a re-export).

Edit: I guess this should be in a new issue maybe — but finding related issues on this repo is hard enough as it is. 🤷

[jyn514]

cargo-deadlinks does report the broken link. I guess that tool should be obsolete now maybe?

(disclaimer: I'm the current maintainer of deadlinks.) cargo-deadlinks is not obsolete for a few reasons:

1. It can be used on non-rust projects, as a normal linkchecker.
2. People still use manual links, intra-doc links are not (and will never be) a hard requirement. So there's still value in checking those.
3. Rustdoc doesn't always report link failures, for example the ones in this issue.

---

Is it not possible to just resolve the issue by considering links in doc inherited via a re-export as being relative to the crate it was defined in?

This is #74481 and is specific to facade crates. Other crates will break if you change the scope you resolve them in for re-exports, see #65983.

[jyn514]

I think it's pretty clear by now this won't happen - fortunately most of the bugs in rustdoc have been fixed.