`rustdoc::broken_intra_doc_links` won't catch obvious invalid links

[SteveLauC]

I tried this code:

Lint rustdoc::broken_intra_doc_links warns by default, but it cannot catch obvious invalid links in the fanotify module of the Nix crate.

See the section Steps to reproduce for how to reproduce this behavior.

I expected to see this happen: explanation

Invalid links will be caught

Instead, this happened: explanation

They are not caught

Meta

rustc --version --verbose:

$ rustc --version --verbose
rustc 1.80.1 (3f5fd8dd4 2024-08-06)
binary: rustc
commit-hash: 3f5fd8dd41153bc5fdca9427e9e05be2c767ba23
commit-date: 2024-08-06
host: aarch64-apple-darwin
release: 1.80.1
LLVM version: 18.1.7

Backtrace

no backtrace

Context:

Today I found some invalid links in the Nix crate, and fixed them in this PR nix-rust/nix#2493, then I am surprised that they weren't caught by this lint

Steps to reproduce

$ git clone https://github.com/nix-rust/nix.git
$ cd nix
$ git reset --hard 82301035e4af3ca7903ba1abaf1955b2de61c8d5 # This is a commit where the invalid links exist
$ cargo doc --target x86_64-unknown-linux-gnu --all-features

    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.03s
   Generated /Users/steve/Documents/workspace/test/target/x86_64-unknown-linux-gnu/doc/nix/index.html
$ echo $?
0

[fmease]

None of the links / inline code blocks touched in PR nix-rust/nix#2493 were intra-doc links to begin with (which is a requirement for this lint).

The links whose target/ref ended in .html were regular hyperlinks pointing at a URL, not intra-doc links. So this wouldn't apply. Although I could've sworn we once had a migration lint from manual URL-based intra-doc links to proper ones. That would've detected them.

Scanning all inline code blocks for intra-doc link candidates is practically infeasible I think. The implementation wouldn't be that difficult but it would require rustc storing all candidates in the crate metadata for rustdoc to winnow later on. This will likely have a noticable impact on performance and memory usage due to the extra encoding, decoding and filtering. Of course, if there is sufficient interest in creating such a lint, we should just test if what I said actually holds.

[fmease]

So in my view, this boils down to two feature requests, namely two lints:

1. One for detecting manual URL-based intra-doc links. I bet there have already been discussions about this like years ago before my time; one would need to check their resolution, maybe there's an issue for this already.
2. One for detecting inline code blocks that resemble intra-doc links.

[SteveLauC]

Hi, thanks for the quick response! Appreciate it

None of the links / inline code blocks touched in PR nix-rust/nix#2493 were intra-doc links to begin with (which is a requirement for this lint).

Sorry for confusing them:<

Scanning all inline code blocks for intra-doc link candidates is practically infeasible I think. The implementation wouldn't be that difficult but it would require rustc storing all candidates in the crate metadata for rustdoc to winnow later on. This will likely have a noticable impact on performance and memory usage due to the extra encoding, decoding and filtering. Of course, if there is sufficient interest in creating such a lint, we should just test if what I said actually holds.

Thanks for the explanation of the impl details.

---

Then to solve my issue, I guess I need to use something similar to cargo-deadlinks?