diff --git a/src/librustdoc/lint.rs b/src/librustdoc/lint.rs index 91f92b799889b..f3052dd9ead82 100644 --- a/src/librustdoc/lint.rs +++ b/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> = Lazy::new(|| { vec![ BROKEN_INTRA_DOC_LINKS, @@ -209,6 +223,8 @@ pub(crate) static RUSTDOC_LINTS: Lazy> = Lazy::new(|| { MISSING_CRATE_LEVEL_DOCS, UNESCAPED_BACKTICKS, REDUNDANT_EXPLICIT_LINKS, + BROKEN_FOOTNOTE, + UNUSED_FOOTNOTE_DEFINITION, ] }); diff --git a/src/librustdoc/passes/lint.rs b/src/librustdoc/passes/lint.rs index 7740d14148bf0..bb952b32393cf 100644 --- a/src/librustdoc/passes/lint.rs +++ b/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); diff --git a/src/librustdoc/passes/lint/footnotes.rs b/src/librustdoc/passes/lint/footnotes.rs new file mode 100644 index 0000000000000..b67babbcdb754 --- /dev/null +++ b/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 { + 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, + ); + }), + ); + } +} diff --git a/tests/rustdoc-ui/lints/broken-footnote.rs b/tests/rustdoc-ui/lints/broken-footnote.rs new file mode 100644 index 0000000000000..3b97cbe89e865 --- /dev/null +++ b/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 diff --git a/tests/rustdoc-ui/lints/broken-footnote.stderr b/tests/rustdoc-ui/lints/broken-footnote.stderr new file mode 100644 index 0000000000000..80d7c93333e4e --- /dev/null +++ b/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 + diff --git a/tests/rustdoc-ui/lints/unused-footnote.rs b/tests/rustdoc-ui/lints/unused-footnote.rs new file mode 100644 index 0000000000000..a71e20ff6d500 --- /dev/null +++ b/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 diff --git a/tests/rustdoc-ui/lints/unused-footnote.stderr b/tests/rustdoc-ui/lints/unused-footnote.stderr new file mode 100644 index 0000000000000..d227cef181df3 --- /dev/null +++ b/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 +