Rust-clippy: False positive in doc_markdown lint: reference style link to type in external crate

[lopopolo]

smallvec is a crate in my Cargo.toml. Clippy emits a warning when I use a reference style markdown comment to link to the fully qualified smallvec::SmallVec type in this crate.

I tried this code:

    /// Consume the array and return the inner
    /// [`SmallVec<[T; INLINE_CAPACITY]>`].
    ///
    /// # Examples
    ///
    /// ```
    /// # use smallvec::SmallVec;
    /// use spinoso_array::{INLINE_CAPACITY, SmallArray};
    /// let ary = SmallArray::from(&[1, 2, 4]);
    /// let vec: SmallVec<[i32; INLINE_CAPACITY]> = ary.into_inner();
    /// ```
    ///
    /// [`SmallVec<[T; INLINE_CAPACITY]>`]: smallvec::SmallVe

And also this code:

    /// Consume the array and return the inner
    /// [`SmallVec<[T; INLINE_CAPACITY]>`].
    ///
    /// # Examples
    ///
    /// ```
    /// # use smallvec::SmallVec;
    /// use spinoso_array::{INLINE_CAPACITY, SmallArray};
    /// let ary = SmallArray::from(&[1, 2, 4]);
    /// let vec: SmallVec<[i32; INLINE_CAPACITY]> = ary.into_inner();
    /// ```
    ///
    /// [`SmallVec<[T; INLINE_CAPACITY]>`]: SmallVec

I expected to see this happen: no lint errors. rustdoc can build this doc comment correctly.

Instead, this happened:

cargo clippy --workspace --all-features
warning: you should put `smallvec::SmallVec` between ticks in the documentation
   --> spinoso-array/src/array/smallvec/mod.rs:303:45
    |
303 |     /// [`SmallVec<[T; INLINE_CAPACITY]>`]: smallvec::SmallVec
    |                                             ^^^^^^^^^^^^^^^^^^
    |
note: the lint level is defined here
   --> spinoso-array/src/lib.rs:2:9
    |
2   | #![warn(clippy::pedantic)]
    |         ^^^^^^^^^^^^^^^^
    = note: `#[warn(clippy::doc_markdown)]` implied by `#[warn(clippy::pedantic)]`
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown

cargo clippy --workspace --all-features
warning: you should put `SmallVec` between ticks in the documentation
   --> spinoso-array/src/array/smallvec/mod.rs:303:45
    |
303 |     /// [`SmallVec<[T; INLINE_CAPACITY]>`]: SmallVec
    |                                             ^^^^^^^^
    |
note: the lint level is defined here
   --> spinoso-array/src/lib.rs:2:9
    |
2   | #![warn(clippy::pedantic)]
    |         ^^^^^^^^^^^^^^^^
    = note: `#[warn(clippy::doc_markdown)]` implied by `#[warn(clippy::pedantic)]`
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown

Meta

• cargo clippy -V: clippy 0.0.212 (5c1f21c3b 2020-07-13)
• rustc -Vv:
  rustc 1.45.0 (5c1f21c3b 2020-07-13) binary: rustc commit-hash: 5c1f21c3b82297671ad3ae1e8c942d2ca92e84f2 commit-date: 2020-07-13 host: x86_64-apple-darwin release: 1.45.0 LLVM version: 10.0

Backtrace

<backtrace>

[nahuakang]

I'm completely new to the project but would like to sign up and give it a try if that's ok :)

[nahuakang]

@flip1995 @Manishearth @phansch @yaahc Would anyone have time to point me in a direction here? :pray:

[flip1995]

@nahuakang I answered your e-mail. Welcome to Clippy!

[flip1995]

After working on this issue together with @nahuakang, we found out that the issue is not with the lint, but with the doc comment itself. The reason this is linted is because you have [ ] brackets in your link text, which trip the parser.

I just tested this with cargo doc and also rustdoc fails to parse this link:

As a workaround, you can write the link as:

    /// Consume the array and return the inner
    /// [`SmallVec<[T; INLINE_CAPACITY]>`][SmallVec].
    ///
    /// [SmallVec]: SmallVec

This won't trigger the lint.

@nahuakang Can you write a comment about this in the Known Problems section of the lint documentation, please?