Add new unused_footnote_definition rustdoc lint - #137858
Conversation
This comment has been minimized.
This comment has been minimized.
c17e182 to
8550b0a
Compare
|
Fixed tidy. |
40b5fa2 to
27c7ec4
Compare
|
Updated to use new |
|
☔ The latest upstream changes (presumably #140726) made this pull request unmergeable. Please resolve the merge conflicts. |
lolbinarycat
left a comment
There was a problem hiding this comment.
One main issue (possibly parsing footnotes as code blocks) and a bunch of small nits.
| let mut footnote_definitions = FxHashMap::default(); | ||
|
|
||
| let options = Options::ENABLE_FOOTNOTES; | ||
| let mut parser = Parser::new_ext(dox, options).into_offset_iter().peekable(); |
There was a problem hiding this comment.
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?
| 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 }); | ||
| } |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
The docs are outdated. FootnoteReference is only emitted if the footnote definition exists.
There was a problem hiding this comment.
glad to see the docs getting fixed, but i still believe this code handles code blocks incorrectly.
There was a problem hiding this comment.
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.
|
@rustbot author |
|
This PR is still based on #137803, which I thought was a bad idea because of the false positives. The |
27c7ec4 to
2cdc54b
Compare
This comment has been minimized.
This comment has been minimized.
|
Sorry for the delay, finally applied suggestions. |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
6074417 to
8f2b963
Compare
This comment has been minimized.
This comment has been minimized.
|
@rustbot ready |
| 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 == "]" => |
There was a problem hiding this comment.
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.
| @@ -0,0 +1,7 @@ | |||
| #![deny(rustdoc::broken_footnote)] | |||
There was a problem hiding this comment.
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
Add new `unused_footnote_definition` rustdoc lint try-job: i686-gnu-nopt-1
|
Ah finally. \o/ @bors r=notriddle |
…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)
…, 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)
…, 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)
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)
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
|
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 @bors rollup=never rustc-perf Instruction countOur most reliable metric. Used to determine the overall result above. However, even this metric can be noisy.
Max RSS (memory usage)This perf run didn't have relevant results for this metric. CyclesResults (primary -1.4%)A less reliable metric. May be of interest, but not used to determine the overall result above.
Binary sizeThis perf run didn't have relevant results for this metric. Bootstrap: 455.642s -> 455.618s (-0.01%) |
|
This caused a tiny overall regression for @rustbot label: +perf-regression-triaged |
Rollup of 13 pull requests Successful merges: - rust-lang#160976 (Ensure TLS accesses don't call the global allocator through panic (part 2)) - rust-lang#160438 ([rustdoc] Change table odd table rows background color to not make it the same as inline code) - rust-lang#160985 (self-profile more of borrowck) - rust-lang#137858 (Add new `unused_footnote_definition` rustdoc lint) - rust-lang#159566 (Add support for generics in `offload`and remove `no_mangle` attribute) - rust-lang#160676 (rustc_public: split `def`s out of `ty`) - rust-lang#160861 (rustc_parse: suggest removing semicolon before `if` block) - rust-lang#160958 (Remove unused `#[non_exhaustive]` in library) - rust-lang#160978 (move resolve_path to Session inherent method) - rust-lang#160990 (Remove old cfg parser which is now dead code) - rust-lang#160991 (Add offload component on nightly) - rust-lang#160999 (doc changes to expect messages in process.rs) - rust-lang#161003 (Also warn if an invalid `doc` attribute is used on a macro invocation)
Rollup of 13 pull requests Successful merges: - rust-lang/rust#160976 (Ensure TLS accesses don't call the global allocator through panic (part 2)) - rust-lang/rust#160438 ([rustdoc] Change table odd table rows background color to not make it the same as inline code) - rust-lang/rust#160985 (self-profile more of borrowck) - rust-lang/rust#137858 (Add new `unused_footnote_definition` rustdoc lint) - rust-lang/rust#159566 (Add support for generics in `offload`and remove `no_mangle` attribute) - rust-lang/rust#160676 (rustc_public: split `def`s out of `ty`) - rust-lang/rust#160861 (rustc_parse: suggest removing semicolon before `if` block) - rust-lang/rust#160958 (Remove unused `#[non_exhaustive]` in library) - rust-lang/rust#160978 (move resolve_path to Session inherent method) - rust-lang/rust#160990 (Remove old cfg parser which is now dead code) - rust-lang/rust#160991 (Add offload component on nightly) - rust-lang/rust#160999 (doc changes to expect messages in process.rs) - rust-lang/rust#161003 (Also warn if an invalid `doc` attribute is used on a macro invocation)
Pkgsrc changes: * Adapt to changes in vendored crate versions. * Version & checksum changes. Upstream changes: Version 1.99.0 (2026-10-01) ========================== Language -------- - [Add allow-by-default `raw_borrows_via_references` lint that checks for references that decay immediately into raw borrows](rust-lang/rust#138230) - [Extend `unconditional_panic` lint to function calls that panic when the chunks/windows size is zero] (rust-lang/rust#153563) - [Stabilize C-variadic function definitions] (rust-lang/rust#155697) - [Stabilize the ability to use `#[unsafe(naked)]` functions to define C-variadic functions (`#![feature(c_variadic_naked_functions)]`).] (rust-lang/rust#159746) - [Trait methods are now resolved on an adjusted never type (producing a FCW)] (rust-lang/rust#156047) - [Coerce from inference variables to trait objects if the inference variable is related via subtyping to a type that is known to be `Sized`] (rust-lang/rust#157820) - [Stabilize `#[my_macro] mod foo;`] (rust-lang/rust#157857). This allows outlined modules (`mod foo;`) anywhere in the body of a custom attribute or derive macro. - [Fix the `overflowing_literals` lint with repeated negation] (rust-lang/rust#158302). For instance, it will now no longer lint on `--128_i8`, which is already detected by the `arithmetic_overflow` lint. - [Add POSIX symbols to the `invalid_runtime_symbol_definitions` and `suspicious_runtime_symbol_definitions` lints] (rust-lang/rust#158522) - [Lint unused `#[path]` attributes on inline modules] (rust-lang/rust#158835) - [Enable `unreachable_cfg_select_predicates` lint as part of `unused` lint group] (rust-lang/rust#159179) - [Stabilize passing 128-bit integers via vector registers with `asm!` on x86] (rust-lang/rust#159525) - [Explicitly document that some allocations are allowed to grow in-place (but none are allowed to shrink)] (rust-lang/rust#159729) - We now [guarantee] (rust-lang/rust#159730) that the contents of an `UnsafeCell` can be accessed without going through `get` - [The `invalid_reference_casting` lint was adjusted accordingly] (rust-lang/rust#159960) - [Account for globally enabled target features in `global_asm!`] (rust-lang/rust#160594) - [Warn if an invalid `doc` attribute is used on a macro invocation] (rust-lang/rust#161003) Compiler -------- - [Convert `-Ctarget-cpu` into a target-modifier for AVR, AMDGCN and NVPTX] (rust-lang/rust#150732) - [Enable `static_position_independent_executables` on all gnu and musl targets] (rust-lang/rust#158510) - When providing a suggestion about a missing method, rustc now prefers an exactly matching name from a [doc alias attribute] (https://doc.rust-lang.org/rustdoc/advanced-features.html#add-aliases-for-an-item-in-documentation-search) over a similarity search from other method names. If your new users sometimes expect a method under a different name, adding a doc alias will now help them find it via rustc suggestions, in addition to helping them find it via rustdoc search: [When suggesting method names, prefer *exact* doc aliases over similar names](rust-lang/rust#160369) Platform Support ---------------- - [Promote `riscv64-unknown-linux-musl` to Tier 2 with host tools] (rust-lang/rust#158766) Refer to Rust's [platform support page][platform-support-doc] for more information on Rust's tiered platform support. [platform-support-doc]: https://doc.rust-lang.org/rustc/platform-support.html Libraries --------- - Iteration on `RangeInclusive` (`a..=b` ranges) is now [optimized better in some circumstances] (rust-lang/rust#155114). As a side effect of this, the behavior of `RangeInclusive` values that has already been exhausted (as an iterator) has changed. For example, the return values of `start()` and `end()` on such ranges may return different values, and using such ranges as slice indexes may have different behavior. These behaviors were not guaranteed to be stable, so these changes are considered to not be breaking changes. - [Relax `transmute_copy` to accept `?Sized` types] (rust-lang/rust#155989) - [Update `transmute_copy` to use a non-unwinding panic] (rust-lang/rust#155989) - [Don't escape U+FF9E and U+FF9F in `escape_debug_ext`] (rust-lang/rust#158057) - [Re-export `core::fmt::NumBuffer` in `alloc` (and `std`)] (rust-lang/rust#161430) Stabilized APIs --------------- - [`IntoIterator` for `Box<[T; N]>`] (https://doc.rust-lang.org/stable/std/iter/trait.IntoIterator.html#impl-IntoIterator-for-Box%3C%5BT;+N%5D,+A%3E) - [`IntoIterator` for `&Box<[T; N]>`] (https://doc.rust-lang.org/stable/std/iter/trait.IntoIterator.html#impl-IntoIterator-for-%26Box%3C%5BT;+N%5D,+A%3E) - [`IntoIterator` for `&mut Box<[T; N]>`] (https://doc.rust-lang.org/stable/std/iter/trait.IntoIterator.html#impl-IntoIterator-for-%26mut+Box%3C%5BT;+N%5D,+A%3E) - [`VecDeque::retain_back`] (https://doc.rust-lang.org/stable/std/collections/struct.VecDeque.html#method.retain_back) - [`core::ffi::VaList`] (https://doc.rust-lang.org/stable/core/ffi/struct.VaList.html) - [`Box::into_non_null`] (https://doc.rust-lang.org/stable/std/boxed/struct.Box.html#method.into_non_null) - [`Box::from_non_null`] (https://doc.rust-lang.org/stable/std/boxed/struct.Box.html#method.from_non_null) - [`Vec::into_parts`] (https://doc.rust-lang.org/stable/std/vec/struct.Vec.html#method.into_parts) - [`Vec::from_parts`] (https://doc.rust-lang.org/stable/std/vec/struct.Vec.html#method.from_parts) - [`core::mem::size_of_val_raw`] (https://doc.rust-lang.org/stable/core/mem/fn.size_of_val_raw.html) - [`core::mem::align_of_val_raw`] (https://doc.rust-lang.org/stable/core/mem/fn.align_of_val_raw.html) - [`core::alloc::Layout::for_value_raw`] (https://doc.rust-lang.org/stable/core/alloc/struct.Layout.html#method.for_value_raw) - [`String::from_utf8_lossy_owned`] (https://doc.rust-lang.org/stable/std/string/struct.String.html#method.from_utf8_lossy_owned) - [`string::FromUtf8Error::into_utf8_lossy`] (https://doc.rust-lang.org/stable/std/string/struct.FromUtf8Error.html#method.into_utf8_lossy) - [`FusedIterator for StepBy<I>`] (https://doc.rust-lang.org/stable/std/iter/struct.StepBy.html#impl-FusedIterator-for-StepBy%3CI%3E) - [`std::fs::set_times`] (https://doc.rust-lang.org/stable/std/fs/fn.set_times.html) - [`std::fs::set_times_nofollow`] (https://doc.rust-lang.org/stable/std/fs/fn.set_times_nofollow.html) Cargo ----- - Add a new built-in profile `debug`. This is a preparation for transitioning the `dev` profile away from debugging to give a saner default for faster development iterations. Currently there is no difference between `dev` and `debug` profiles. [docs] (https://doc.rust-lang.org/nightly/cargo/reference/profiles.html#debug-1) [#17214] (rust-lang/cargo#17214) - Workspace members on edition 2024 or later can now override an inherited workspace dependency's `default-features` field. For example, `serde = { workspace = true, default-features = false }` now turns off default features even when the workspace definition enables them. On earlier editions, `default-features = false` is ignored with a warning. ([RFC 3945] (rust-lang/rfcs#3945)) [#17126](rust-lang/cargo#17126) - Incremental compilation is now disabled by default when running in CI. CI is detected via the CI environment variable. [#17220] (rust-lang/cargo#17220) See also the [full Cargo changelog] (https://doc.rust-lang.org/nightly/cargo/CHANGELOG.html#cargo-199-2026-10-01) Rustdoc ----- - [Add new `unused_footnote_definition` rustdoc lint] (rust-lang/rust#137858) - Smarter filtering of trait impls yields performance improvements of 20% on average and up to 40% on some real-world crates. ([1] (rust-lang/rust#159623), [2](rust-lang/rust#159721), [3](rust-lang/rust#159779), [4](rust-lang/rust#159854), [5](rust-lang/rust#159091)) Compatibility Notes ------------------- - [Fully deprecate the legacy integral modules] (rust-lang/rust#146882). For example, `std::i32::MAX` should be accessed via `i32::MAX` instead. - [Upgrade `no_mangle_generic_items` into hard error] (rust-lang/rust#154585) - [The `Pin::new_unchecked` has had its safety invariants changed slightly] (rust-lang/rust#156935) - [Do not promote references to extern statics] (rust-lang/rust#157641) - [Ensure that the inferred types of `let` patterns typecheck] (rust-lang/rust#157841) - [hermit/fs: Return `unsupported()` instead of `from_raw_os_error(22)`] (rust-lang/rust#158247) - [Fixed a bug where `#[repr(simd)]` was accidentally allowed on macro invocations on stable Rust] (rust-lang/rust#158523) - [Abort const-eval when there are generics in the type of the value being produced] (rust-lang/rust#159504) - [Attributes not applying to anything are now an error in code blocks in doc comments] (rust-lang/rust#159849) - [`Box::leak`: tell people to avoid unleaking] (rust-lang/rust#160323) - [PowerPC inline ASM: Fix scalar floats being in the wrong vector lane on little endian] (rust-lang/rust#160441) - [Do not take `doc(cfg())` into account when filtering doctests] (rust-lang/rust#159014) - [Infer anonymous lifetimes in the types of associated consts as `'static`] (rust-lang/rust#156508) - Macros that expand to a semicolon now produce a warning lint (`semicolon_in_expressions_from_non_local_macros`) even when the macro comes from another crate. Previously, such warnings only appeared for macros from the same crate, to avoid showing warnings that can't be fixed locally; however, this masked problems, as integration tests from the crate providing the macro get compiled as a separate crate, so tests often wouldn't reveal this issue. If you encounter a lint like this, please make sure to report it to the crate providing the macro so they can fix it; don't just silence it in your own crate. - [`semicolon_in_expressions_from_macros`: Lint on non-local macros too] (rust-lang/rust#159222) - [Split non-local `semicolon_in_expressions_from_macros` into a separate lint] (rust-lang/rust#159700) Internal Changes ---------------- These changes do not affect any public interfaces of Rust, but they represent significant improvements to the performance or internals of rustc and related tools. - [Update to LLVM 23] (rust-lang/rust#158734)
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