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

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

View all comments

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

+    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?

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

+            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.

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.

GuillaumeGomez · 2026-02-25T23:31:11Z

@rustbot ready

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

+                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:17:47Z

@@ -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

JonathanBrouwer · 2026-06-27T22:46:49Z

💔 I suspect this PR failed tests as part of a rollup
@bors r-

After fixing the problem, consider running a try job for the failed job before re-approving.

Link to failure: #158498 (comment)

This is a separate issue from what caused me to start the try job
@bors r-

rust-bors · 2026-06-27T22:46:54Z

This pull request was unapproved.

View changes since this unapproval

GuillaumeGomez · 2026-06-27T22:47:38Z

Ah my apologies. Gonna take a look at it tomorrow then.

GuillaumeGomez · 2026-06-29T10:06:17Z

Rebased the PR. Let's try the failed jobs.

@bors try jobs=auto,i686-gnu-nopt-1

Add new `unused_footnote_definition` rustdoc lint try-job: auto try-job: i686-gnu-nopt-1

rust-bors · 2026-06-29T10:07:13Z

💔 Test for a162f68 failed: CI. Failed job:

Calculate job matrix (web logs, enhanced plaintext logs)

GuillaumeGomez · 2026-06-29T11:39:02Z

@bors try jobs=i686-gnu-nopt-1

Add new `unused_footnote_definition` rustdoc lint try-job: i686-gnu-nopt-1

rust-bors · 2026-06-29T13:33:44Z

💔 Test for a366c3a failed: CI. Failed job:

try - i686-gnu-nopt-1 (web logs, enhanced plaintext logs)

rustbot · 2026-06-30T14:51:24Z

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-06-30T14:52:01Z

I rebased and changed nothing. Test passed locally too. Gonna try again and investigate further if it still fails.

@bors try jobs=i686-gnu-nopt-1

rust-bors · 2026-06-30T14:52:08Z

⌛ Trying commit 6a2cf7f with merge 13fc244…

To cancel the try build, run the command @bors try cancel.

Workflow: https://github.com/rust-lang/rust/actions/runs/28453583673

Add new `unused_footnote_definition` rustdoc lint try-job: i686-gnu-nopt-1

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

Comment thread src/librustdoc/passes/lint/footnotes.rs Outdated

Comment thread src/librustdoc/passes/lint/footnotes.rs Outdated

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 force-pushed the unused_footnote_def branch from 6074417 to 8f2b963 Compare February 25, 2026 15:45

This comment has been minimized.

Sign in to view

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 removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Mar 10, 2026

rust-bors Bot 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-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Jun 27, 2026

GuillaumeGomez force-pushed the unused_footnote_def branch from 738c160 to 357445b Compare June 29, 2026 10:05

This comment has been minimized.

Sign in to view

rust-bors Bot pushed a commit that referenced this pull request Jun 29, 2026

Auto merge of #137858 - GuillaumeGomez:unused_footnote_def, r=<try>

a162f68

Add new `unused_footnote_definition` rustdoc lint try-job: auto try-job: i686-gnu-nopt-1

This comment has been minimized.

Sign in to view

rust-bors Bot pushed a commit that referenced this pull request Jun 29, 2026

Auto merge of #137858 - GuillaumeGomez:unused_footnote_def, r=<try>

a366c3a

Add new `unused_footnote_definition` rustdoc lint try-job: i686-gnu-nopt-1

This comment has been minimized.

Sign in to view

GuillaumeGomez and others added 8 commits June 30, 2026 16:50

Add new rustdoc broken_footnote lint

fb1ff14

Add ui test for rustdoc broken_footnote lint

378cc53

Add new unused_footnote_definition rustdoc lint

176b1fa

Add ui test for new unused_footnote_definition rustdoc lint

35dd2a5

Improve description of new rustdoc lints

2a6588e

Remove outdated comment

44afd9b

Add extra "broken_footnote" lint ui test

9529bcd

Fix backslashes and line breaks in footnote lint

6a2cf7f

GuillaumeGomez force-pushed the unused_footnote_def branch from 357445b to 6a2cf7f Compare June 30, 2026 14:51

rust-bors Bot pushed a commit that referenced this pull request Jun 30, 2026

Auto merge of #137858 - GuillaumeGomez:unused_footnote_def, r=<try>

13fc244

Add new `unused_footnote_definition` rustdoc lint try-job: i686-gnu-nopt-1

Uh oh!

Uh oh!

Conversation

GuillaumeGomez commented Mar 1, 2025 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

lolbinarycat May 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lolbinarycat May 22, 2025

Choose a reason for hiding this comment

Uh oh!

notriddle May 29, 2025

Choose a reason for hiding this comment

Uh oh!

lolbinarycat May 29, 2025

Choose a reason for hiding this comment

Uh oh!

lolbinarycat Mar 9, 2026

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.

This comment has been minimized.

GuillaumeGomez commented Feb 25, 2026

Uh oh!

notriddle Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

notriddle Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

JonathanBrouwer commented Jun 27, 2026

Uh oh!

rust-bors Bot commented Jun 27, 2026

Uh oh!

GuillaumeGomez commented Jun 27, 2026

Uh oh!

This comment has been minimized.

GuillaumeGomez commented Jun 29, 2026

Uh oh!

This comment has been minimized.

rust-bors Bot commented Jun 29, 2026

Uh oh!

This comment has been minimized.

GuillaumeGomez commented Jun 29, 2026

Uh oh!

This comment has been minimized.

rust-bors Bot commented Jun 29, 2026

Uh oh!

This comment has been minimized.

rustbot commented Jun 30, 2026

Uh oh!

GuillaumeGomez commented Jun 30, 2026

Uh oh!

GuillaumeGomez commented Mar 1, 2025 •

edited by rustbot

Loading

notriddle commented Aug 21, 2025 •

edited

Loading

rust-bors Bot commented Jun 30, 2026 •

edited

Loading