Auto merge of #6107 - nahuakang:ref_style_link_false_positive, r=flip1995

Ref style link false positive

This PR does not fix #5834, but it records the problematic link text as a **known problem** inside `doc_markdown` lint.

r? `@flip1995`

- [ ] Followed [lint naming conventions][lint_naming]
- [ ] Added passing UI tests (including committed `.stderr` file)
- [x] `cargo test` passes locally
- [x] Executed `cargo dev update_lints`
- [ ] Added lint documentation
- [x] Run `cargo dev fmt`

---

*Please keep the line below*
changelog: Document problematic link text style as known problem for `doc_markdown`

1 files changed, 13 insertions, 0 deletions

diff --git a/clippy_lints/src/doc.rs b/clippy_lints/src/doc.rs
index 62bb70af06e..07f604cf714 100644
--- a/clippy_lints/src/doc.rs
+++ b/clippy_lints/src/doc.rs
@@ -32,6 +32,11 @@ declare_clippy_lint! {
     /// **Known problems:** Lots of bad docs won’t be fixed, what the lint checks
     /// for is limited, and there are still false positives.
     ///
+    /// In addition, when writing documentation comments, including `[]` brackets
+    /// inside a link text would trip the parser. Therfore, documenting link with
+    /// `[`SmallVec<[T; INLINE_CAPACITY]>`]` and then [`SmallVec<[T; INLINE_CAPACITY]>`]: SmallVec
+    /// would fail.
+    ///
     /// **Examples:**
     /// ```rust
     /// /// Do something with the foo_bar parameter. See also
@@ -39,6 +44,14 @@ declare_clippy_lint! {
     /// // ^ `foo_bar` and `that::other::module::foo` should be ticked.
     /// fn doit(foo_bar: usize) {}
     /// ```
+    ///
+    /// ```rust
+    /// // Link text with `[]` brackets should be written as following:
+    /// /// Consume the array and return the inner
+    /// /// [`SmallVec<[T; INLINE_CAPACITY]>`][SmallVec].
+    /// /// [SmallVec]: SmallVec
+    /// fn main() {}
+    /// ```
     pub DOC_MARKDOWN,
     pedantic,
     "presence of `_`, `::` or camel-case outside backticks in documentation"