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\]pubstructBackslashEscape;
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 footnotepubstructSpecials;
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

rust-bors · 2026-08-12T12:57:09Z

Try build cancelled. Cancelled workflows:

https://github.com/rust-lang/rust/actions/runs/31597827104

GuillaumeGomez · 2026-08-12T13:00:00Z

Hopefully this time it'll work out.

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

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

rust-bors · 2026-08-12T15:00:27Z

☀️ Try build successful (CI)
Build commit: cd6c798 (cd6c798f92f2779a147129bee56a0d19d15e3337)
Base parent: 41fb9d4 (41fb9d458726b5effbd64c7c1beced947ea03242)

GuillaumeGomez · 2026-08-12T15:01:18Z

Ah finally. \o/

@bors r=notriddle

rust-bors · 2026-08-12T15:01:21Z

📌 Commit 116fdd1 has been approved by notriddle

It is now in the queue for this repository.

…uwer Rollup of 4 pull requests Successful merges: - #137803 (Add new rustdoc `broken_footnote` lint) - #160975 (Remove target argument from get_proc_macros) - #160861 (rustc_parse: suggest removing semicolon before `if` block) - #160990 (Remove old cfg parser which is now dead code) Failed merges: - #137858 (Add new `unused_footnote_definition` rustdoc lint)

@notriddle

…, r=notriddle Add new `unused_footnote_definition` rustdoc lint Follow-up of rust-lang#137803 (where the two first commits come from). It adds a new lint which checks for unused footnote definitions. r? @notriddle

…uwer Rollup of 5 pull requests Successful merges: - #160975 (Remove target argument from get_proc_macros) - #160985 (self-profile more of borrowck) - #137858 (Add new `unused_footnote_definition` rustdoc lint) - #160861 (rustc_parse: suggest removing semicolon before `if` block) - #160990 (Remove old cfg parser which is now dead code)

@notriddle

…, r=notriddle Add new `unused_footnote_definition` rustdoc lint Follow-up of rust-lang#137803 (where the two first commits come from). It adds a new lint which checks for unused footnote definitions. r? @notriddle

Rollup of 13 pull requests Successful merges: - #160976 (Ensure TLS accesses don't call the global allocator through panic (part 2)) - #160438 ([rustdoc] Change table odd table rows background color to not make it the same as inline code) - #160985 (self-profile more of borrowck) - #137858 (Add new `unused_footnote_definition` rustdoc lint) - #159566 (Add support for generics in `offload`and remove `no_mangle` attribute) - #160676 (rustc_public: split `def`s out of `ty`) - #160861 (rustc_parse: suggest removing semicolon before `if` block) - #160958 (Remove unused `#[non_exhaustive]` in library) - #160978 (move resolve_path to Session inherent method) - #160990 (Remove old cfg parser which is now dead code) - #160991 (Add offload component on nightly) - #160999 (doc changes to expect messages in process.rs) - #161003 (Also warn if an invalid `doc` attribute is used on a macro invocation)

@notriddle

Rollup merge of #137858 - GuillaumeGomez:unused_footnote_def, r=notriddle Add new `unused_footnote_definition` rustdoc lint Follow-up of #137803 (where the two first commits come from). It adds a new lint which checks for unused footnote definitions. r? @notriddle

rust-timer · 2026-08-18T07:54:53Z

Finished benchmarking commit (47c7eb4): comparison URL.

Overall result: ❌ regressions - please read:

Benchmarking means the PR may be perf-sensitive. It's automatically marked not fit for rolling up. Overriding is possible but disadvised: it risks changing compiler perf.

Next, please: If you can, justify the regressions found in this try perf run in writing along with @rustbot label: +perf-regression-triaged. If not, fix the regressions and do another perf run. Neutral or positive results will clear the label automatically.

@bors rollup=never rustc-perf
@rustbot label: -S-waiting-on-perf +perf-regression

Instruction count

Our most reliable metric. Used to determine the overall result above. However, even this metric can be noisy.

	mean	range	count
Regressions ❌ (primary)	0.3%	[0.1%, 0.8%]	10
Regressions ❌ (secondary)	0.1%	[0.1%, 0.1%]	2
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	0.3%	[0.1%, 0.8%]	10

Max RSS (memory usage)

This perf run didn't have relevant results for this metric.

Cycles

Results (primary -1.4%)

A less reliable metric. May be of interest, but not used to determine the overall result above.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-1.4%	[-1.4%, -1.4%]	1
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	-1.4%	[-1.4%, -1.4%]	1

Binary size

This perf run didn't have relevant results for this metric.

Bootstrap: 455.642s -> 455.618s (-0.01%)
Artifact size: 396.40 MiB -> 396.36 MiB (-0.01%)

Kobzol · 2026-08-18T10:47:38Z

This caused a tiny overall regression for doc builds, which makes sense, as it is a new lint.

@rustbot label: +perf-regression-triaged

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