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,152 @@
+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, TagEnd};
+use rustc_resolve::rustdoc::source_span_for_markdown_range;
+
+use crate::clean::Item;
+use crate::core::DocContext;
+
+// based on
+// https://github.com/pulldown-cmark/pulldown-cmark/blob/fc8fe713f58d7f4495038b48fe76c1f101fb3af1/pulldown-cmark/src/linklabel.rs#L65
+
+fn scan_ch(ch: u8, dox: &[u8], i: &mut usize) -> Option<()> {
+    if dox.get(*i) == Some(&ch) {
+        *i += 1;
+        Some(())
+    } else {
+        None
+    }
+}
+
+fn scan_footnote_ref(dox: &[u8], in_table: bool) -> Option<usize> {
+    let mut i = 0;
+    scan_ch(b'[', dox, &mut i)?;
+    scan_ch(b'^', dox, &mut i)?;
+    if dox.get(i) == Some(&b']') {
+        return None;
+    }
+    while let Some(&ch) = dox.get(i) {
+        if ch == b']'
+            || ch == b'['
+            || ch == b'\r'
+            || ch == b'\n'
+            || (in_table && ch == b'|')
+            // these two cause false negatives in obscure corner cases,
+            // but there's another warning from the unescaped_backticks
+            // and invalid_html_tags lints when they do
+            || ch == b'`'
+            || ch == b'<'
+        {
+            break;
+        } else if in_table
+            && ch == b'\\'
+            && dox.get(i + 1) == Some(&b'\\')
+            && dox.get(i + 2) == Some(&b'|')
+        {
+            i += 3;
+        } else if ch == b'\\' && dox.get(i + 1).copied().map_or(false, is_ascii_punctuation) {
+            i += 2;
+        } else {
+            i += 1;
+        }
+    }
+    scan_ch(b']', dox, &mut i)?;
+    Some(i)
+}
+
+fn is_ascii_punctuation(c: u8) -> bool {
+    c < 128 && (PUNCT_MASKS_ASCII[(c / 16) as usize] & (1 << (c & 15))) != 0
+}
+
+const PUNCT_MASKS_ASCII: [u16; 8] = [
+    0x0000, // U+0000...U+000F
+    0x0000, // U+0010...U+001F
+    0xfffe, // U+0020...U+002F
+    0xfc00, // U+0030...U+003F
+    0x0001, // U+0040...U+004F
+    0xf800, // U+0050...U+005F
+    0x0001, // U+0060...U+006F
+    0x7800, // U+0070...U+007F
+];
+
+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 mut in_table = false;
+
+    let options = Options::ENABLE_FOOTNOTES | Options::ENABLE_TABLES;
+    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.starts_with("[")
+                    && (span.start == 0 || dox.as_bytes()[span.start - 1] != b'\\')
+                    && let Some(len) =
+                        scan_footnote_ref(&dox.as_bytes()[span.start..], in_table) =>
+            {
+                missing_footnote_references
+                    .insert(Range { start: span.start, end: span.start + len });
+            }
+            Event::FootnoteReference(label) => {
+                footnote_references.insert(label);
+            }
+            Event::Start(Tag::FootnoteDefinition(label)) => {
+                footnote_definitions.insert(label, span.start + 1);
+            }
+            Event::Start(Tag::Table(_)) => in_table = true,
+            Event::End(TagEnd::Table) => in_table = false,
+            _ => {}
+        }
+    }
+
+    #[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,69 @@
+#![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]
+
+//! [^*] 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
+//~| ERROR: no footnote definition matching this footnote
+//!
+//! Mixed with actual emphasis:
+//!
+//! [^a ***b] foobar [^c*** d]
+//~^ ERROR: no footnote definition matching this footnote
+//~| ERROR: no footnote definition matching this footnote
+//! [^e ***f] foobar [^g*** h]
+//!
+//! [^e ***f]: test footnote
+//! [^g*** h]: test footnote`
+//!
+//! [^foo | bar]
+//~^ ERROR: no footnote definition matching this footnote
+//!
+//! |  col  | col  |
+//! |-------|------|
+//! | [^foo | bar] |
+//!
+//! |  col  |  col  |
+//! |-------|-------|
+//! | [^foo \| bar] |
+//~^ ERROR: no footnote definition matching this footnote
+//!
+//! |  col  |  col   |
+//! |-------|--------|
+//! | [^foo \\| bar] |
+//~^ ERROR: no footnote definition matching this footnote
+//!
+//! Code spans and HTML have higher binding power than footnotes:
+//!
+//! [^foo `bar] baz` [^foo <bar title="]"></bar>

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

@@ -0,0 +1,104 @@
+error: no footnote definition matching this footnote
+  --> $DIR/broken-footnote.rs:36:11
+   |
+LL | //! [^\_] [^\[\]] so can escaped characters
+   |           -^^^^^^
+   |           |
+   |           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:29:5
+   |
+LL | //! [^*] special characters can appear within footnote references
+   |     -^^^
+   |     |
+   |     help: if it should not be a footnote, escape it: `\[^*]`
+
+error: no footnote definition matching this footnote
+  --> $DIR/broken-footnote.rs:50:5
+   |
+LL | //! [^foo | bar]
+   |     -^^^^^^^^^^^
+   |     |
+   |     help: if it should not be a footnote, escape it: `\[^foo | bar]`
+
+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:59:7
+   |
+LL | //! | [^foo \| bar] |
+   |       -^^^^^^^^^^^^
+   |       |
+   |       help: if it should not be a footnote, escape it: `\[^foo \| bar]`
+
+error: no footnote definition matching this footnote
+  --> $DIR/broken-footnote.rs:36:5
+   |
+LL | //! [^\_] [^\[\]] so can escaped characters
+   |     -^^^^
+   |     |
+   |     help: if it should not be a footnote, escape it: `\[^\_]`
+
+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: `\[^*]`
+
+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:64:7
+   |
+LL | //! | [^foo \| bar] |
+   |       -^^^^^^^^^^^^^
+   |       |
+   |       help: if it should not be a footnote, escape it: `\[^foo \| bar]`
+
+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: no footnote definition matching this footnote
+  --> $DIR/broken-footnote.rs:42:22
+   |
+LL | //! [^a ***b] foobar [^c*** d]
+   |                      -^^^^^^^^
+   |                      |
+   |                      help: if it should not be a footnote, escape it: `\[^c*** d]`
+
+error: no footnote definition matching this footnote
+  --> $DIR/broken-footnote.rs:42:5
+   |
+LL | //! [^a ***b] foobar [^c*** d]
+   |     -^^^^^^^^
+   |     |
+   |     help: if it should not be a footnote, escape it: `\[^a ***b]`
+
+error: aborting due to 12 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
+