Add new rustdoc broken_footnote lint

[GuillaumeGomez]

I think in this case, instead of spawning unpportable_markdown, we should instead notify that this footnote reference doesn't have an associated definition.

r? @notriddle

[notriddle]

Fixes #137740.

I think you might have misunderstood the issue description. "The term of what is meant by anchors is borrowed from" a description of this style of anchor links. It doesn't say anything about footnotes.

/// Consider [panics](std::alloc::GlobalAllocator#Panics) on allocation.
//                                               ^^^^^^^ anchor

[GuillaumeGomez]

I indeed misunderstood and went on a completely different path. Although I still think that this PR is useful. I plan to send a follow-up PR for unused footnote references as well. ^^'

I removed the "fixes" mention though.

[notriddle]

This lint seems too noisy to belong in core.

Review case F1 of #121659 (comment), where [^a-zA-Z0-9] is syntactically valid as a footnote reference, but not intended to be parsed as one. Following the suggestion (to add \ to the front) makes the plain-text representation harder to read, and Rustdoc is already doing what the author wanted, so where's the problem?

If the goal of this lint is to catch typo-ed footnotes, then there should be an unused footnote definition, somewhere, that the author tried and failed to reference. Those are guaranteed to be a problem: either they typo-ed the reference, or they never intended a footnote at all (but still got one).

[GuillaumeGomez]

That's why we suggest to escape the [ if it was not intended. Like I said, I'm also planning to send a PR for unused footnote definitions. But even without it, I think it makes sense to warn that a footnote reference doesn't match anything and suggest to escape it if it's not meant to be a footnote.

[notriddle]

That's why we suggest to escape the [ if it was not intended.

Doing that makes the doc comment less plain-text (noisier).

[GuillaumeGomez]

After discussing with @notriddle, it was decided to move the implementation of this lint into its own file.

[bors]

☔ The latest upstream changes (presumably #140726) made this pull request unmergeable. Please resolve the merge conflicts.

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[GuillaumeGomez]

Fixed merge conflict. Ping @notriddle

[GuillaumeGomez]

And updated to new APIs.

[GuillaumeGomez]

I was sure x.py fmt was adding missing newlines at the end of files. Oh well, added it.