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.