Add new rustdoc broken_footnote lint

src/librustdoc/lint.rs

@@ -196,6 +196,20 @@ declare_rustdoc_lint! {
     "detects redundant explicit links in doc comments"
 }
 
+declare_rustdoc_lint! {
+    /// This lint checks for uses of footnote references without definition.
+    BROKEN_FOOTNOTE,
+    Warn,
+    "detects footnote references with no associated definition"
+}
+
+declare_rustdoc_lint! {
+    /// This lint checks if all footnote definitions are used.
+    UNUSED_FOOTNOTE_DEFINITION,
+    Warn,
+    "detects unused footnote definitions"
+}
+
 pub(crate) static RUSTDOC_LINTS: Lazy<Vec<&'static Lint>> = Lazy::new(|| {
     vec![
         BROKEN_INTRA_DOC_LINKS,
@@ -209,6 +223,8 @@ pub(crate) static RUSTDOC_LINTS: Lazy<Vec<&'static Lint>> = Lazy::new(|| {
         MISSING_CRATE_LEVEL_DOCS,
         UNESCAPED_BACKTICKS,
         REDUNDANT_EXPLICIT_LINKS,
+        BROKEN_FOOTNOTE,
+        UNUSED_FOOTNOTE_DEFINITION,
     ]
 });
 

src/librustdoc/passes/lint.rs

@@ -3,6 +3,7 @@
 
 mod bare_urls;
 mod check_code_block_syntax;
+mod footnotes;
 mod html_tags;
 mod redundant_explicit_links;
 mod unescaped_backticks;
@@ -41,6 +42,7 @@ impl DocVisitor<'_> for Linter<'_, '_> {
             if may_have_link {
                 bare_urls::visit_item(self.cx, item, hir_id, &dox);
                 redundant_explicit_links::visit_item(self.cx, item, hir_id);
+                footnotes::visit_item(self.cx, item, hir_id, &dox);
             }
             if may_have_code {
                 check_code_block_syntax::visit_item(self.cx, item, &dox);

src/librustdoc/passes/lint/footnotes.rs

@@ -0,0 +1,96 @@
+use std::ops::Range;
+
+use rustc_data_structures::fx::{FxHashMap, FxHashSet};
+use rustc_errors::DiagDecorator;
+use rustc_hir::HirId;
+use rustc_lint_defs::Applicability;
+use rustc_resolve::rustdoc::pulldown_cmark::{Event, Options, Parser, Tag};
+use rustc_resolve::rustdoc::source_span_for_markdown_range;
+
+use crate::clean::Item;
+use crate::core::DocContext;
+
+pub(crate) fn visit_item(cx: &DocContext<'_>, item: &Item, hir_id: HirId, dox: &str) {
+    let tcx = cx.tcx;
+
+    let mut missing_footnote_references = FxHashSet::default();
+    let mut footnote_references = FxHashSet::default();
+    let mut footnote_definitions = FxHashMap::default();
+
+    let options = Options::ENABLE_FOOTNOTES;
+    let mut parser = Parser::new_ext(dox, options).into_offset_iter().peekable();
+    while let Some((event, span)) = parser.next() {
+        match event {
+            Event::Text(text)
+                if &*text == "["
+                    && let Some((Event::Text(_), range)) = parser.next()
+                    && dox[span.end..range.end].starts_with('^') =>
+            {
+                loop {
+                    let Some((Event::Text(text), new_span)) = parser.peek() else { break };
+                    if &**text != "]" {
+                        parser.next();
+                        continue;
+                    }
+                    let text = &dox[span.end..new_span.end];
+                    if !text.ends_with("\\]") {
+                        missing_footnote_references
+                            .insert(Range { start: span.start, end: new_span.end });
+                    }
+                    break;
+                }
+            }
+            Event::FootnoteReference(label) => {
+                footnote_references.insert(label);
+            }
+            Event::Start(Tag::FootnoteDefinition(label)) => {
+                footnote_definitions.insert(label, span.start + 1);
+            }
+            _ => {}
+        }
+    }
+
+    #[allow(rustc::potential_query_instability)]
+    for (footnote, span) in footnote_definitions {
+        if !footnote_references.contains(&footnote) {
+            let (span, _) = source_span_for_markdown_range(
+                tcx,
+                dox,
+                &(span..span + 1),
+                &item.attrs.doc_strings,
+            )
+            .unwrap_or_else(|| (item.attr_span(tcx), false));
+
+            tcx.emit_node_span_lint(
+                crate::lint::UNUSED_FOOTNOTE_DEFINITION,
+                hir_id,
+                span,
+                DiagDecorator(|lint| {
+                    lint.primary_message("unused footnote definition");
+                }),
+            );
+        }
+    }
+
+    #[allow(rustc::potential_query_instability)]
+    for span in missing_footnote_references {
+        let ref_span = source_span_for_markdown_range(tcx, dox, &span, &item.attrs.doc_strings)
+            .map(|(span, _)| span)
+            .unwrap_or_else(|| item.attr_span(tcx));
+
+        tcx.emit_node_span_lint(
+            crate::lint::BROKEN_FOOTNOTE,
+            hir_id,
+            ref_span,
+            DiagDecorator(|lint| {
+                lint.primary_message("no footnote definition matching this footnote");
+                lint.span_suggestion(
+                    ref_span.shrink_to_lo(),
+                    "if it should not be a footnote, escape it",
+                    format!("\\{}", &dox[span]),
+                    Applicability::MaybeIncorrect,
+                );
+            }),
+        );
+    }
+}

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

@@ -0,0 +1,27 @@
+#![deny(rustdoc::broken_footnote)]
+
+//! Footnote referenced [^1]. And [^2]. And [^bla].
+//!
+//! [^1]: footnote defined
+//~^^^ ERROR: no footnote definition matching this footnote
+//~| ERROR: no footnote definition matching this footnote
+
+//! [^*] special characters can appear within footnote references
+//~^ ERROR: no footnote definition matching this footnote
+//!
+//! [^**]
+//!
+//! [^**]: not an error
+//!
+//! [^\_] so can escaped characters
+//~^ ERROR: no footnote definition matching this footnote
+
+// Backslash escaped footnotes should not be recognized:
+//! [\^4]
+//!
+//! [^5\]
+//!
+//! \[^yup]
+//!
+//! [^foo\
+//! bar]

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

@@ -0,0 +1,40 @@
+error: no footnote definition matching this footnote
+  --> $DIR/broken-footnote.rs:9:5
+   |
+LL | //! [^*] special characters can appear within footnote references
+   |     -^^^
+   |     |
+   |     help: if it should not be a footnote, escape it: `\[^*]`
+   |
+note: the lint level is defined here
+  --> $DIR/broken-footnote.rs:1:9
+   |
+LL | #![deny(rustdoc::broken_footnote)]
+   |         ^^^^^^^^^^^^^^^^^^^^^^^^
+
+error: no footnote definition matching this footnote
+  --> $DIR/broken-footnote.rs:3:35
+   |
+LL | //! Footnote referenced [^1]. And [^2]. And [^bla].
+   |                                   -^^^
+   |                                   |
+   |                                   help: if it should not be a footnote, escape it: `\[^2]`
+
+error: no footnote definition matching this footnote
+  --> $DIR/broken-footnote.rs:3:45
+   |
+LL | //! Footnote referenced [^1]. And [^2]. And [^bla].
+   |                                             -^^^^^
+   |                                             |
+   |                                             help: if it should not be a footnote, escape it: `\[^bla]`
+
+error: no footnote definition matching this footnote
+  --> $DIR/broken-footnote.rs:16:5
+   |
+LL | //! [^\_] so can escaped characters
+   |     -^^^^
+   |     |
+   |     help: if it should not be a footnote, escape it: `\[^\_]`
+
+error: aborting due to 4 previous errors
+

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

@@ -0,0 +1,9 @@
+// This test ensures that the `rustdoc::unused_footnote` lint is working as expected.
+
+#![deny(rustdoc::unused_footnote_definition)]
+
+//! Footnote referenced. [^2]
+//!
+//! [^1]: footnote defined
+//! [^2]: footnote defined
+//~^^ ERROR: unused_footnote_definition

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

@@ -0,0 +1,14 @@
+error: unused footnote definition
+  --> $DIR/unused-footnote.rs:7:6
+   |
+LL | //! [^1]: footnote defined
+   |      ^
+   |
+note: the lint level is defined here
+  --> $DIR/unused-footnote.rs:3:9
+   |
+LL | #![deny(rustdoc::unused_footnote_definition)]
+   |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+error: aborting due to 1 previous error
+