detect ['foo'] (quotes, not backticks) in doc comments

[cameron1024]

What it does

Highlights when someone writes:

/// ['foo::Bar']

when they probably meant

/// [`foo::Bar`]

This recently caught me out. cargo doc reported no broken links, but I had a couple lurking that were using this format, so were missed by the broken link check.

The characters are visually similar enough to be very easy to confuse

Lint Name

doc_link_with_quotes

Category

suspicious

Advantage

Typing ['foo::Bar'] (with single quotes) is almost certainly a mistake, either because they genuinely think that is the correct syntax, or as a typo. Having clippy flag likely leads to better

Drawbacks

There are likely some false positives, since this syntax is meaningful in other languages (e.g. in JS/TS, Python and Dart (probably more than that) they represent list containing a string literal, though in those cases I suspect it would already be enclosed in backticks, so the actual false positive rate is likely quite low

Example

/// Does the same thing as ['bar']
fn foo() {}

Could be written as:

/// Does the same thing as [`bar`]
fn foo() {}

[cameron1024]

FWIW, if people think this would be helpful, I'd be happy to try implementing this myself. I've not worked on clippy before but keen to learn 😁

[llogiq]

Sure! I guess the best starting point is writing a UI test (a .rs file in tests/ui containing Rust code the lint should pick up on) and then looking at clippy_lints/doc.rs where the other documentation lints are.

Feel free to comment here or on your PR if you have questions or encounter any problem.