avoid doc-link-with-quotes in code blocks

Author: llogiq

clippy_lints/src/doc.rs

@@ -198,6 +198,29 @@ declare_clippy_lint! {
     "presence of `fn main() {` in code examples"
 }
 
+declare_clippy_lint! {
+    /// ### What it does
+    /// Detects the syntax `['foo']` in documentation comments (notice quotes instead of backticks)
+    /// outside of code blocks
+    /// ### Why is this bad?
+    /// It is likely a typo when defining an intra-doc link
+    ///
+    /// ### Example
+    /// ```rust
+    /// /// See also: ['foo']
+    /// fn bar() {}
+    /// ```
+    /// Use instead:
+    /// ```rust
+    /// /// See also: [`foo`]
+    /// fn bar() {}
+    /// ```
+    #[clippy::version = "1.63.0"]
+    pub DOC_LINK_WITH_QUOTES,
+    pedantic,
+    "possible typo for an intra-doc link"
+}
+
 #[expect(clippy::module_name_repetitions)]
 #[derive(Clone)]
 pub struct DocMarkdown {
@@ -214,9 +237,14 @@ impl DocMarkdown {
     }
 }
 
-impl_lint_pass!(DocMarkdown =>
-    [DOC_MARKDOWN, MISSING_SAFETY_DOC, MISSING_ERRORS_DOC, MISSING_PANICS_DOC, NEEDLESS_DOCTEST_MAIN]
-);
+impl_lint_pass!(DocMarkdown => [
+    DOC_LINK_WITH_QUOTES,
+    DOC_MARKDOWN,
+    MISSING_SAFETY_DOC,
+    MISSING_ERRORS_DOC,
+    MISSING_PANICS_DOC,
+    NEEDLESS_DOCTEST_MAIN
+]);
 
 impl<'tcx> LateLintPass<'tcx> for DocMarkdown {
     fn check_crate(&mut self, cx: &LateContext<'tcx>) {
@@ -612,6 +640,18 @@ fn check_doc<'a, Events: Iterator<Item = (pulldown_cmark::Event<'a>, Range<usize
                         check_code(cx, &text, edition, span);
                     }
                 } else {
+                    if in_link.is_some() {
+                        if trimmed_text.starts_with('\'') && trimmed_text.ends_with('\'') {
+                            // fix the span to only point at the text within the link
+                            let lo = span.lo() + BytePos::from_usize(range.start - begin);
+                            span_lint(
+                                cx,
+                                DOC_LINK_WITH_QUOTES,
+                                span.with_lo(lo).with_hi(lo + BytePos::from_usize(text.len())),
+                                "possible intra-doc link using quotes instead of backticks",
+                            );
+                        }
+                    }
                     // Adjust for the beginning of the current `Event`
                     let span = span.with_lo(span.lo() + BytePos::from_usize(range.start - begin));
                     text_to_check.push((text, span));

clippy_lints/src/doc_link_with_quotes.rs

@@ -118,12 +118,12 @@ store.register_lints(&[
     disallowed_names::DISALLOWED_NAMES,
     disallowed_script_idents::DISALLOWED_SCRIPT_IDENTS,
     disallowed_types::DISALLOWED_TYPES,
+    doc::DOC_LINK_WITH_QUOTES,
     doc::DOC_MARKDOWN,
     doc::MISSING_ERRORS_DOC,
     doc::MISSING_PANICS_DOC,
     doc::MISSING_SAFETY_DOC,
     doc::NEEDLESS_DOCTEST_MAIN,
-    doc_link_with_quotes::DOC_LINK_WITH_QUOTES,
     double_parens::DOUBLE_PARENS,
     drop_forget_ref::DROP_COPY,
     drop_forget_ref::DROP_NON_DROP,

clippy_lints/src/lib.register_lints.rs

@@ -20,10 +20,10 @@ store.register_group(true, "clippy::pedantic", Some("clippy_pedantic"), vec![
     LintId::of(dereference::REF_BINDING_TO_REFERENCE),
     LintId::of(derive::EXPL_IMPL_CLONE_ON_COPY),
     LintId::of(derive::UNSAFE_DERIVE_DESERIALIZE),
+    LintId::of(doc::DOC_LINK_WITH_QUOTES),
     LintId::of(doc::DOC_MARKDOWN),
     LintId::of(doc::MISSING_ERRORS_DOC),
     LintId::of(doc::MISSING_PANICS_DOC),
-    LintId::of(doc_link_with_quotes::DOC_LINK_WITH_QUOTES),
     LintId::of(empty_enum::EMPTY_ENUM),
     LintId::of(enum_variants::MODULE_NAME_REPETITIONS),
     LintId::of(eta_reduction::REDUNDANT_CLOSURE_FOR_METHOD_CALLS),

clippy_lints/src/lib.register_pedantic.rs

@@ -204,7 +204,6 @@ mod disallowed_names;
 mod disallowed_script_idents;
 mod disallowed_types;
 mod doc;
-mod doc_link_with_quotes;
 mod double_parens;
 mod drop_forget_ref;
 mod duplicate_mod;
@@ -864,7 +863,6 @@ pub fn register_plugins(store: &mut rustc_lint::LintStore, sess: &Session, conf:
     store.register_early_pass(|| Box::new(single_char_lifetime_names::SingleCharLifetimeNames));
     store.register_late_pass(move |_| Box::new(manual_bits::ManualBits::new(msrv)));
     store.register_late_pass(|_| Box::new(default_union_representation::DefaultUnionRepresentation));
-    store.register_early_pass(|| Box::new(doc_link_with_quotes::DocLinkWithQuotes));
     store.register_late_pass(|_| Box::<only_used_in_recursion::OnlyUsedInRecursion>::default());
     let allow_dbg_in_tests = conf.allow_dbg_in_tests;
     store.register_late_pass(move |_| Box::new(dbg_macro::DbgMacro::new(allow_dbg_in_tests)));

clippy_lints/src/lib.rs

@@ -4,9 +4,14 @@ fn main() {
     foo()
 }
 
-/// Calls ['bar']
+/// Calls ['bar'] uselessly
 pub fn foo() {
     bar()
 }
 
+/// # Examples
+/// This demonstrates issue \#8961
+/// ```
+/// let _ = vec!['w', 'a', 't'];
+/// ```
 pub fn bar() {}

tests/ui/doc_link_with_quotes.rs

@@ -1,8 +1,8 @@
 error: possible intra-doc link using quotes instead of backticks
-  --> $DIR/doc_link_with_quotes.rs:7:1
+  --> $DIR/doc_link_with_quotes.rs:7:12
    |
-LL | /// Calls ['bar']
-   | ^^^^^^^^^^^^^^^^^
+LL | /// Calls ['bar'] uselessly
+   |            ^^^^^
    |
    = note: `-D clippy::doc-link-with-quotes` implied by `-D warnings`