Add new `unused_footnote_definition` rustdoc lint by GuillaumeGomez · Pull Request #137858 · rust-lang/rust

GuillaumeGomez · 2025-03-01T16:22:08Z

Follow-up of #137803 (where the two first commits come from).

It adds a new lint which checks for unused footnote definitions.

r? @notriddle

GuillaumeGomez · 2025-03-01T19:58:23Z

Fixed tidy.

GuillaumeGomez · 2025-03-11T14:15:00Z

Updated to use new footnote lint code instead.

bors · 2025-05-07T05:04:56Z

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

lolbinarycat

One main issue (possibly parsing footnotes as code blocks) and a bunch of small nits.

lolbinarycat · 2025-05-22T17:56:45Z

src/librustdoc/passes/lint/footnotes.rs

+    let mut footnote_definitions = FxHashMap::default();
+
+    let options = Options::ENABLE_FOOTNOTES;
+    let mut parser = Parser::new_ext(dox, options).into_offset_iter().peekable();


Should we be making sure the lint is enabled before invoking the parser? I know the other lints don't do this, but maybe they should?

src/librustdoc/passes/lint/footnotes.rs

lolbinarycat · 2025-05-22T18:31:58Z

src/librustdoc/passes/lint/footnotes.rs

+            Event::Text(text)
+                if &*text == "["
+                    && let Some((Event::Text(text), _)) = parser.peek()
+                    && text.trim_start().starts_with('^')
+                    && parser.next().is_some()
+                    && let Some((Event::Text(text), end_span)) = parser.peek()
+                    && &**text == "]" =>
+            {
+                missing_footnote_references.insert(Range { start: span.start, end: end_span.end });
+            }


It is quite odd that pulldown_cmark isn't emmitting some form of FootnoteReference here despite the docs saying they might not map to an actual definition.

In any case, I don't think this implementation is correct, since Text events are emitted for the bodies of all blocks. Crucially, this includes code blocks, which certainly should not be parsed for footnotes. An integration test should be added to show that we are not wrongfully parsing footnotes within code blocks.

One way to handle this is to track the type of the last Start event and make sure it isn't CodeBlock. luckily other blocks can't appear within code blocks so we don't have to track the full stack of tags. We might want to clear that variable whenever we reach an End event, but I'm not sure if the text after a code block will always get its own separate Paragraph event or not. An integration test with an unused footnote directly after a code block should clear this up.

The docs are outdated. FootnoteReference is only emitted if the footnote definition exists.

pulldown-cmark/pulldown-cmark#1038

glad to see the docs getting fixed, but i still believe this code handles code blocks incorrectly.

This could be easily answered by some tests that exercise the case of broken markdown inside a code block, as well as a footnote definition outside the code block referenced by markdown inside the block, and the other way around.

tests/rustdoc-ui/lints/unused-footnote.rs

src/librustdoc/lint.rs

lolbinarycat · 2025-08-21T17:19:49Z

@rustbot author

notriddle · 2025-08-21T17:54:05Z

This PR is still based on #137803, which I thought was a bad idea because of the false positives.

The unused_footnote_definition lint shouldn't have any false positives, so it's fine, but this PR needs rebased to remove the other, rejected lint.

GuillaumeGomez · 2026-01-26T13:40:57Z

Sorry for the delay, finally applied suggestions.

src/librustdoc/passes/lint/footnotes.rs

rustbot · 2026-02-25T15:45:55Z

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 · 2026-02-25T23:31:11Z

@rustbot ready

notriddle · 2026-03-10T04:10:54Z

src/librustdoc/passes/lint/footnotes.rs

+                if &*text == "["
+                    && let Some((Event::Text(text), _)) = parser.peek()
+                    && text.trim_start().starts_with('^')
+                    && parser.next().is_some()
+                    && let Some((Event::Text(text), end_span)) = parser.peek()
+                    && &**text == "]" =>


This parsing logic doesn't fully account for backslashes or special characters. This test case fails (it's a false positive, because it produces a warning when it shouldn't):

/// Backslash escaped footnotes should not be recognized: /// /// [\^4] /// /// [^5\] pub struct BackslashEscape;

And so does this one (it's a false negative, since it's supposed to produce a warning, but it doesn't):

/// Footnotes can contain asterisks, underscores, and other specials: /// /// [^*] //~^ ERROR: no footnote definition matching this footnote /// /// [^_] //~^ ERROR: no footnote definition matching this footnote /// /// [^<inside></inside>] //~^ ERROR: no footnote definition matching this footnote pub struct Specials;

To do this correctly, you need to parse the source text, not the returned event stream. Mostly copy scan_link_label, but strip out everything unrelated to footnotes.

notriddle · 2026-03-10T04:15:41Z

tests/rustdoc-ui/lints/broken-footnote.rs

These moved into tests/rustdoc-html now...

notriddle · 2026-03-10T04:17:47Z

tests/rustdoc-ui/lints/broken-footnote.rs

@@ -0,0 +1,7 @@
+#![deny(rustdoc::broken_footnote)]


A selection of many good corner cases to test this lint against can be found here: https://pulldown-cmark.github.io/pulldown-cmark/specs/footnotes.html

rustbot assigned notriddle Mar 1, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Mar 1, 2025

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the unused_footnote_def branch from c17e182 to 8550b0a Compare March 1, 2025 19:58

GuillaumeGomez force-pushed the unused_footnote_def branch 2 times, most recently from 40b5fa2 to 27c7ec4 Compare March 11, 2025 14:14

lolbinarycat requested changes May 22, 2025

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 21, 2025

GuillaumeGomez force-pushed the unused_footnote_def branch from 27c7ec4 to 2cdc54b Compare January 26, 2026 13:40

This comment has been minimized.

Sign in to view

notriddle reviewed Jan 31, 2026

View reviewed changes

src/librustdoc/passes/lint/footnotes.rs Outdated Show resolved Hide resolved

src/librustdoc/passes/lint/footnotes.rs Show resolved Hide resolved

This comment has been minimized.

Sign in to view

rustbot added the has-merge-commits PR has merge commits, merge with caution. label Feb 25, 2026

GuillaumeGomez added 6 commits February 25, 2026 16:03

Add new rustdoc broken_footnote lint

fd41af8

Add ui test for rustdoc broken_footnote lint

a70e979

Add new unused_footnote_definition rustdoc lint

83b774c

Add ui test for new unused_footnote_definition rustdoc lint

5f3ad25

Improve description of new rustdoc lints

f41ddc6

Remove outdated comment

8f2b963

GuillaumeGomez force-pushed the unused_footnote_def branch from 6074417 to 8f2b963 Compare February 25, 2026 15:45

rustbot removed has-merge-commits PR has merge commits, merge with caution. S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Feb 25, 2026

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Feb 25, 2026

notriddle requested changes Mar 10, 2026

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 10, 2026

Uh oh!

Conversation

GuillaumeGomez commented Mar 1, 2025

Uh oh!

This comment has been minimized.

GuillaumeGomez commented Mar 1, 2025

Uh oh!

GuillaumeGomez commented Mar 11, 2025

Uh oh!

bors commented May 7, 2025

Uh oh!

lolbinarycat left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lolbinarycat commented Aug 21, 2025

Uh oh!

notriddle commented Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

GuillaumeGomez commented Jan 26, 2026

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

rustbot commented Feb 25, 2026

Uh oh!

GuillaumeGomez commented Feb 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

notriddle commented Aug 21, 2025 •

edited

Loading