From 11759d1bad5cebc1af170090bc423f2494cfbc40 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Tue, 12 Mar 2024 15:14:44 +0100 Subject: [PATCH 1/3] Don't emit `doc_markdown` lint for missing backticks if it's inside a quote --- clippy_lints/src/doc/markdown.rs | 17 +++++++++++++---- clippy_lints/src/doc/mod.rs | 7 +++++-- 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/clippy_lints/src/doc/markdown.rs b/clippy_lints/src/doc/markdown.rs index d2f147565917..1add02af3101 100644 --- a/clippy_lints/src/doc/markdown.rs +++ b/clippy_lints/src/doc/markdown.rs @@ -8,7 +8,14 @@ use url::Url; use crate::doc::DOC_MARKDOWN; -pub fn check(cx: &LateContext<'_>, valid_idents: &FxHashSet, text: &str, span: Span, code_level: isize) { +pub fn check( + cx: &LateContext<'_>, + valid_idents: &FxHashSet, + text: &str, + span: Span, + code_level: isize, + blockquote_level: isize, +) { for orig_word in text.split(|c: char| c.is_whitespace() || c == '\'') { // Trim punctuation as in `some comment (see foo::bar).` // ^^ @@ -46,11 +53,11 @@ pub fn check(cx: &LateContext<'_>, valid_idents: &FxHashSet, text: &str, span.parent(), ); - check_word(cx, word, span, code_level); + check_word(cx, word, span, code_level, blockquote_level); } } -fn check_word(cx: &LateContext<'_>, word: &str, span: Span, code_level: isize) { +fn check_word(cx: &LateContext<'_>, word: &str, span: Span, code_level: isize, blockquote_level: isize) { /// Checks if a string is upper-camel-case, i.e., starts with an uppercase and /// contains at least two uppercase letters (`Clippy` is ok) and one lower-case /// letter (`NASA` is ok). @@ -97,7 +104,9 @@ fn check_word(cx: &LateContext<'_>, word: &str, span: Span, code_level: isize) { } // We assume that mixed-case words are not meant to be put inside backticks. (Issue #2343) - if code_level > 0 || (has_underscore(word) && has_hyphen(word)) { + // + // We also assume that backticks are not necessary if inside a quote. (Issue #10262) + if code_level > 0 || blockquote_level > 0 || (has_underscore(word) && has_hyphen(word)) { return; } diff --git a/clippy_lints/src/doc/mod.rs b/clippy_lints/src/doc/mod.rs index 003d26b7b89d..10fc9ef6ecf5 100644 --- a/clippy_lints/src/doc/mod.rs +++ b/clippy_lints/src/doc/mod.rs @@ -7,7 +7,7 @@ use clippy_utils::{is_entrypoint_fn, method_chain_args}; use pulldown_cmark::Event::{ Code, End, FootnoteReference, HardBreak, Html, Rule, SoftBreak, Start, TaskListMarker, Text, }; -use pulldown_cmark::Tag::{CodeBlock, Heading, Item, Link, Paragraph}; +use pulldown_cmark::Tag::{BlockQuote, CodeBlock, Heading, Item, Link, Paragraph}; use pulldown_cmark::{BrokenLink, CodeBlockKind, CowStr, Options}; use rustc_ast::ast::Attribute; use rustc_data_structures::fx::FxHashSet; @@ -602,6 +602,7 @@ fn check_doc<'a, Events: Iterator, Range, Range, isize)> = Vec::new(); let mut paragraph_range = 0..0; let mut code_level = 0; + let mut blockquote_level = 0; for (event, range) in events { match event { @@ -612,6 +613,8 @@ fn check_doc<'a, Events: Iterator, Range blockquote_level += 1, + End(BlockQuote) => blockquote_level -= 1, Start(CodeBlock(ref kind)) => { in_code = true; if let CodeBlockKind::Fenced(lang) = kind { @@ -663,7 +666,7 @@ fn check_doc<'a, Events: Iterator, Range Date: Tue, 12 Mar 2024 15:15:19 +0100 Subject: [PATCH 2/3] Add regression test for #10262 --- tests/ui/doc/issue_10262.fixed | 8 ++++++++ tests/ui/doc/issue_10262.rs | 8 ++++++++ tests/ui/doc/issue_10262.stderr | 15 +++++++++++++++ 3 files changed, 31 insertions(+) create mode 100644 tests/ui/doc/issue_10262.fixed create mode 100644 tests/ui/doc/issue_10262.rs create mode 100644 tests/ui/doc/issue_10262.stderr diff --git a/tests/ui/doc/issue_10262.fixed b/tests/ui/doc/issue_10262.fixed new file mode 100644 index 000000000000..8ca6f3e9718f --- /dev/null +++ b/tests/ui/doc/issue_10262.fixed @@ -0,0 +1,8 @@ +#![warn(clippy::doc_markdown)] + +// Should only warn for the first line! +/// `AviSynth` documentation: +//~^ ERROR: item in documentation is missing backticks +/// +/// > AvisynthPluginInit3 may be called more than once with different IScriptEnvironments. +pub struct Foo; diff --git a/tests/ui/doc/issue_10262.rs b/tests/ui/doc/issue_10262.rs new file mode 100644 index 000000000000..67183b63cdf0 --- /dev/null +++ b/tests/ui/doc/issue_10262.rs @@ -0,0 +1,8 @@ +#![warn(clippy::doc_markdown)] + +// Should only warn for the first line! +/// AviSynth documentation: +//~^ ERROR: item in documentation is missing backticks +/// +/// > AvisynthPluginInit3 may be called more than once with different IScriptEnvironments. +pub struct Foo; diff --git a/tests/ui/doc/issue_10262.stderr b/tests/ui/doc/issue_10262.stderr new file mode 100644 index 000000000000..f43d9551e94e --- /dev/null +++ b/tests/ui/doc/issue_10262.stderr @@ -0,0 +1,15 @@ +error: item in documentation is missing backticks + --> tests/ui/doc/issue_10262.rs:4:5 + | +LL | /// AviSynth documentation: + | ^^^^^^^^ + | + = note: `-D clippy::doc-markdown` implied by `-D warnings` + = help: to override `-D warnings` add `#[allow(clippy::doc_markdown)]` +help: try + | +LL | /// `AviSynth` documentation: + | ~~~~~~~~~~ + +error: aborting due to 1 previous error + From 03d7ae81535f9427501da6f7091b73307a9ea908 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 13 Mar 2024 19:31:01 +0100 Subject: [PATCH 3/3] Also handle `
` and `` HTML tags --- clippy_lints/src/doc/mod.rs | 4 ++++ tests/ui/doc/issue_10262.fixed | 4 ++++ tests/ui/doc/issue_10262.rs | 4 ++++ 3 files changed, 12 insertions(+) diff --git a/clippy_lints/src/doc/mod.rs b/clippy_lints/src/doc/mod.rs index 10fc9ef6ecf5..9bf5d2652b36 100644 --- a/clippy_lints/src/doc/mod.rs +++ b/clippy_lints/src/doc/mod.rs @@ -611,6 +611,10 @@ fn check_doc<'a, Events: Iterator, Range blockquote_level += 1, diff --git a/tests/ui/doc/issue_10262.fixed b/tests/ui/doc/issue_10262.fixed index 8ca6f3e9718f..5d067736d556 100644 --- a/tests/ui/doc/issue_10262.fixed +++ b/tests/ui/doc/issue_10262.fixed @@ -5,4 +5,8 @@ //~^ ERROR: item in documentation is missing backticks /// /// > AvisynthPluginInit3 may be called more than once with different IScriptEnvironments. +/// +///
bla AvisynthPluginInit3 bla
+/// +/// bla AvisynthPluginInit3 bla pub struct Foo; diff --git a/tests/ui/doc/issue_10262.rs b/tests/ui/doc/issue_10262.rs index 67183b63cdf0..e2cbd938d5d7 100644 --- a/tests/ui/doc/issue_10262.rs +++ b/tests/ui/doc/issue_10262.rs @@ -5,4 +5,8 @@ //~^ ERROR: item in documentation is missing backticks /// /// > AvisynthPluginInit3 may be called more than once with different IScriptEnvironments. +/// +///
bla AvisynthPluginInit3 bla
+/// +/// bla AvisynthPluginInit3 bla pub struct Foo;