doc_link_code: add check for text[adjacent] style links

This is the lint described at
rust-lang/rust#136308 (comment)
that recommends using HTML to nest links inside code.

CHANGELOG.md

@@ -5530,6 +5530,7 @@ Released 2018-09-13
 [`diverging_sub_expression`]: https://rust-lang.github.io/rust-clippy/master/index.html#diverging_sub_expression
 [`doc_include_without_cfg`]: https://rust-lang.github.io/rust-clippy/master/index.html#doc_include_without_cfg
 [`doc_lazy_continuation`]: https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
+[`doc_link_code`]: https://rust-lang.github.io/rust-clippy/master/index.html#doc_link_code
 [`doc_link_with_quotes`]: https://rust-lang.github.io/rust-clippy/master/index.html#doc_link_with_quotes
 [`doc_markdown`]: https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown
 [`doc_nested_refdefs`]: https://rust-lang.github.io/rust-clippy/master/index.html#doc_nested_refdefs

clippy_lints/src/declared_lints.rs

@@ -139,6 +139,7 @@ pub static LINTS: &[&crate::LintInfo] = &[
     crate::disallowed_types::DISALLOWED_TYPES_INFO,
     crate::doc::DOC_INCLUDE_WITHOUT_CFG_INFO,
     crate::doc::DOC_LAZY_CONTINUATION_INFO,
+    crate::doc::DOC_LINK_CODE_INFO,
     crate::doc::DOC_LINK_WITH_QUOTES_INFO,
     crate::doc::DOC_MARKDOWN_INFO,
     crate::doc::DOC_NESTED_REFDEFS_INFO,

clippy_lints/src/doc/mod.rs

@@ -84,6 +84,28 @@ declare_clippy_lint! {
     "presence of `_`, `::` or camel-case outside backticks in documentation"
 }
 
+declare_clippy_lint! {
+    /// ### What it does
+    /// Checks for links with code directly adjacent to code text:
+    /// `` [`MyItem`]`<`[`u32`]`>` ``.
+    ///
+    /// ### Why is this bad?
+    /// It can be written more simply using HTML-style `<code>` tags.
+    ///
+    /// ### Example
+    /// ```no_run
+    /// //! [`first`](x)`second`
+    /// ```
+    /// Use instead:
+    /// ```no_run
+    /// //! <code>[first](x)second</code>
+    /// ```
+    #[clippy::version = "1.86.0"]
+    pub DOC_LINK_CODE,
+    nursery,
+    "link with code back-to-back with other code"
+}
+
 declare_clippy_lint! {
     /// ### What it does
     /// Checks for the doc comments of publicly visible
@@ -638,6 +660,7 @@ impl Documentation {
 }
 
 impl_lint_pass!(Documentation => [
+    DOC_LINK_CODE,
     DOC_LINK_WITH_QUOTES,
     DOC_MARKDOWN,
     DOC_NESTED_REFDEFS,
@@ -844,6 +867,14 @@ enum Container {
     List(usize),
 }
 
+#[derive(Clone, Copy, Eq, PartialEq)]
+enum CodeCluster {
+    // true means already in a link, so only needs to be followed by code
+    // false means we've hit code, and need to find a link
+    First(usize, bool),
+    Nth(usize, usize),
+}
+
 /// Checks parsed documentation.
 /// This walks the "events" (think sections of markdown) produced by `pulldown_cmark`,
 /// so lints here will generally access that information.
@@ -875,9 +906,40 @@ fn check_doc<'a, Events: Iterator<Item = (pulldown_cmark::Event<'a>, Range<usize
 
     let mut containers = Vec::new();
 
+    let mut code_cluster = None;
+
     let mut events = events.peekable();
 
     while let Some((event, range)) = events.next() {
+        code_cluster = match (code_cluster, &event) {
+            (None, Code(_)) if in_link.is_some() && doc.as_bytes().get(range.start.wrapping_sub(1)) == Some(&b'[') => {
+                Some(CodeCluster::First(range.start - 1, true))
+            },
+            (None, Code(_)) => Some(CodeCluster::First(range.start, false)),
+            (Some(CodeCluster::First(pos, _)), Start(Link { .. })) | (Some(CodeCluster::First(pos, true)), Code(_)) => {
+                Some(CodeCluster::Nth(pos, range.end))
+            },
+            (Some(CodeCluster::Nth(start, end)), Code(_) | Start(Link { .. })) => {
+                Some(CodeCluster::Nth(start, range.end.max(end)))
+            },
+            (code_cluster @ Some(_), Code(_) | End(TagEnd::Link)) => code_cluster,
+            (Some(CodeCluster::First(_, _)) | None, _) => None,
+            (Some(CodeCluster::Nth(start, end)), _) => {
+                if let Some(span) = fragments.span(cx, start..end) {
+                    span_lint_and_then(cx, DOC_LINK_CODE, span, "code link adjacent to code text", |diag| {
+                        let sugg = format!("<code>{}</code>", doc[start..end].replace('`', ""));
+                        diag.span_suggestion_verbose(
+                            span,
+                            "wrap the entire group in `<code>` tags",
+                            sugg,
+                            Applicability::MaybeIncorrect,
+                        );
+                        diag.help("separate code snippets will be shown with a gap");
+                    });
+                }
+                None
+            },
+        };
         match event {
             Html(tag) | InlineHtml(tag) => {
                 if tag.starts_with("<code") {

tests/ui/doc/link_adjacent.fixed

@@ -0,0 +1,52 @@
+#![warn(clippy::doc_link_code)]
+
+//! Test case for code links that are adjacent to code text.
+//!
+//! This is not an example: `first``second`
+//!
+//! Neither is this: [`first`](x)
+//!
+//! Neither is this: [`first`](x) `second`
+//!
+//! Neither is this: [first](x)`second`
+//!
+//! This is: <code>[first](x)second</code>
+//~^ ERROR: adjacent
+//!
+//! So is this <code>first[second](x)</code>
+//~^ ERROR: adjacent
+//!
+//! So is this <code>[first](x)[second](x)</code>
+//~^ ERROR: adjacent
+//!
+//! So is this <code>[first](x)[second](x)[third](x)</code>
+//~^ ERROR: adjacent
+//!
+//! So is this <code>[first](x)second[third](x)</code>
+//~^ ERROR: adjacent
+
+/// Test case for code links that are adjacent to code text.
+///
+/// This is not an example: `first``second` arst
+///
+/// Neither is this: [`first`](x) arst
+///
+/// Neither is this: [`first`](x) `second` arst
+///
+/// Neither is this: [first](x)`second` arst
+///
+/// This is: <code>[first](x)second</code> arst
+//~^ ERROR: adjacent
+///
+/// So is this <code>first[second](x)</code> arst
+//~^ ERROR: adjacent
+///
+/// So is this <code>[first](x)[second](x)</code> arst
+//~^ ERROR: adjacent
+///
+/// So is this <code>[first](x)[second](x)[third](x)</code> arst
+//~^ ERROR: adjacent
+///
+/// So is this <code>[first](x)second[third](x)</code> arst
+//~^ ERROR: adjacent
+pub struct WithTrailing;

tests/ui/doc/link_adjacent.rs

@@ -0,0 +1,52 @@
+#![warn(clippy::doc_link_code)]
+
+//! Test case for code links that are adjacent to code text.
+//!
+//! This is not an example: `first``second`
+//!
+//! Neither is this: [`first`](x)
+//!
+//! Neither is this: [`first`](x) `second`
+//!
+//! Neither is this: [first](x)`second`
+//!
+//! This is: [`first`](x)`second`
+//~^ ERROR: adjacent
+//!
+//! So is this `first`[`second`](x)
+//~^ ERROR: adjacent
+//!
+//! So is this [`first`](x)[`second`](x)
+//~^ ERROR: adjacent
+//!
+//! So is this [`first`](x)[`second`](x)[`third`](x)
+//~^ ERROR: adjacent
+//!
+//! So is this [`first`](x)`second`[`third`](x)
+//~^ ERROR: adjacent
+
+/// Test case for code links that are adjacent to code text.
+///
+/// This is not an example: `first``second` arst
+///
+/// Neither is this: [`first`](x) arst
+///
+/// Neither is this: [`first`](x) `second` arst
+///
+/// Neither is this: [first](x)`second` arst
+///
+/// This is: [`first`](x)`second` arst
+//~^ ERROR: adjacent
+///
+/// So is this `first`[`second`](x) arst
+//~^ ERROR: adjacent
+///
+/// So is this [`first`](x)[`second`](x) arst
+//~^ ERROR: adjacent
+///
+/// So is this [`first`](x)[`second`](x)[`third`](x) arst
+//~^ ERROR: adjacent
+///
+/// So is this [`first`](x)`second`[`third`](x) arst
+//~^ ERROR: adjacent
+pub struct WithTrailing;

tests/ui/doc/link_adjacent.stderr

@@ -0,0 +1,124 @@
+error: code link adjacent to code text
+  --> tests/ui/doc/link_adjacent.rs:13:14
+   |
+LL | //! This is: [`first`](x)`second`
+   |              ^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: separate code snippets will be shown with a gap
+   = note: `-D clippy::doc-link-code` implied by `-D warnings`
+   = help: to override `-D warnings` add `#[allow(clippy::doc_link_code)]`
+help: wrap the entire group in `<code>` tags
+   |
+LL | //! This is: <code>[first](x)second</code>
+   |              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+error: code link adjacent to code text
+  --> tests/ui/doc/link_adjacent.rs:16:16
+   |
+LL | //! So is this `first`[`second`](x)
+   |                ^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: separate code snippets will be shown with a gap
+help: wrap the entire group in `<code>` tags
+   |
+LL | //! So is this <code>first[second](x)</code>
+   |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+error: code link adjacent to code text
+  --> tests/ui/doc/link_adjacent.rs:19:16
+   |
+LL | //! So is this [`first`](x)[`second`](x)
+   |                ^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: separate code snippets will be shown with a gap
+help: wrap the entire group in `<code>` tags
+   |
+LL | //! So is this <code>[first](x)[second](x)</code>
+   |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+error: code link adjacent to code text
+  --> tests/ui/doc/link_adjacent.rs:22:16
+   |
+LL | //! So is this [`first`](x)[`second`](x)[`third`](x)
+   |                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: separate code snippets will be shown with a gap
+help: wrap the entire group in `<code>` tags
+   |
+LL | //! So is this <code>[first](x)[second](x)[third](x)</code>
+   |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+error: code link adjacent to code text
+  --> tests/ui/doc/link_adjacent.rs:25:16
+   |
+LL | //! So is this [`first`](x)`second`[`third`](x)
+   |                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: separate code snippets will be shown with a gap
+help: wrap the entire group in `<code>` tags
+   |
+LL | //! So is this <code>[first](x)second[third](x)</code>
+   |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+error: code link adjacent to code text
+  --> tests/ui/doc/link_adjacent.rs:38:14
+   |
+LL | /// This is: [`first`](x)`second` arst
+   |              ^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: separate code snippets will be shown with a gap
+help: wrap the entire group in `<code>` tags
+   |
+LL | /// This is: <code>[first](x)second</code> arst
+   |              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+error: code link adjacent to code text
+  --> tests/ui/doc/link_adjacent.rs:41:16
+   |
+LL | /// So is this `first`[`second`](x) arst
+   |                ^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: separate code snippets will be shown with a gap
+help: wrap the entire group in `<code>` tags
+   |
+LL | /// So is this <code>first[second](x)</code> arst
+   |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+error: code link adjacent to code text
+  --> tests/ui/doc/link_adjacent.rs:44:16
+   |
+LL | /// So is this [`first`](x)[`second`](x) arst
+   |                ^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: separate code snippets will be shown with a gap
+help: wrap the entire group in `<code>` tags
+   |
+LL | /// So is this <code>[first](x)[second](x)</code> arst
+   |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+error: code link adjacent to code text
+  --> tests/ui/doc/link_adjacent.rs:47:16
+   |
+LL | /// So is this [`first`](x)[`second`](x)[`third`](x) arst
+   |                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: separate code snippets will be shown with a gap
+help: wrap the entire group in `<code>` tags
+   |
+LL | /// So is this <code>[first](x)[second](x)[third](x)</code> arst
+   |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+error: code link adjacent to code text
+  --> tests/ui/doc/link_adjacent.rs:50:16
+   |
+LL | /// So is this [`first`](x)`second`[`third`](x) arst
+   |                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: separate code snippets will be shown with a gap
+help: wrap the entire group in `<code>` tags
+   |
+LL | /// So is this <code>[first](x)second[third](x)</code> arst
+   |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+error: aborting due to 10 previous errors
+