Rust-clippy: doc_markdown a bit too eager

[Keats]

Running the latest clippy on https://github.com/Keats/tera/ gives the following warning:

Compiling tera v0.1.0 (file:///home/vincent/Code/tera)
src/lexer.rs:133:1: 133:94 warning: you should put `HxaD_trXwRE` between ticks in the documentation, #[warn(doc_markdown)] on by default
src/lexer.rs:133 /// Lexer based on the one used in go templates (https://www.youtube.com/watch?v=HxaD_trXwRE)
                 ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
src/lexer.rs:133:1: 133:94 help: for further information visit https://github.com/Manishearth/rust-clippy/wiki#doc_markdown

[mcarton]

IMHO it’s a feature here. Raw links in doc are ugly.
The lint ignores actual markdown links: [go templates](https://www.youtube.com/watch?v=HxaD_trXwRE) is OK.

[tikue]

It does not ignore markdown links:

$ cargo clippy
   Compiling tarpc v0.6.0 (file:///Users/tikue/Documents/rust/tarpc)
warning: you should put `gRPC` between ticks in the documentation, #[warn(doc_markdown)] on by default
  --> src/lib.rs:18:45
   |
18 | //! architectures. Two well-known ones are [gRPC](http://www.grpc.io) and
   |                                             ^^^^

[mcarton]

@tikue It's a feature. It ignores the link (http://…), not but the text (gRPC). Clippy cannot know every possible weird-cased name and thinks it's a variable, so you can add

doc-valid-idents = ["gRPC"]

to clippy.toml to ignore it.

[tikue]

Gotcha. I think that's reasonable. Though I'd be interested to get some numbers on precision with this one...

[Keats]

Running into it again on a markdown link:

warning: you should put `Prevention_Cheat_Sheet` between ticks in the documentation, #[warn(doc_markdown)] on by default
 --> /home/vincent/Code/tera/src/utils.rs:3:76
  |
3 | /// From [OWASP](https://www.owasp.org/index.php/XSS_(Cross_Site_Scripting)_Prevention_Cheat_Sheet)
  |                                                                            ^^^^^^^^^^^^^^^^^^^^^^^
  |
  = help: for further information visit https://github.com/Manishearth/rust-clippy/wiki#doc_markdown

[briansmith]

In https://github.com/briansmith/ring/issues/285#issuecomment-277328045, @pietro wrote:

BTW, currently clippy warns about lack of backticks on documentation [...]. Some of the things clippy warns about are definitively wrong, like SpecialPublications in http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar2.pdf

Example:

/// See [NIST SP 800-56A, revision 2].
///
/// [NIST SP 800-56A, revision 2]:
///     http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar2.pdf
fn foo() { }

[clarfonthey]

@Keats that isn't a valid markdown link; you need to escape the ( ).

[sanmai-NL]

Could we please determine the default value of doc-valid-idents based on empirical data?
A practical approach would be to include the top StackOverflow tags that are proper names. Then we must normalize those to their canonical mixed case form, next add them (manually) to clippy_lints/src/utils/conf.rs. This should only have to be done very infrequently.

[mcarton]

@sanmai-NL While I think it's a good idea how do you expect us to get such a list from a 47396-item list of lower-case IDs?

[sanmai-NL]

@mcarton:
I propose we match the top (the no. of entries doesn’t matter) StackOverflow tags against all mixed-case English Wikipedia article titles. Mixed-case meaning, having uppercase letters after the initial. We can match pairs based on the lowest edit distance observed, given a tag, against each title. If I wasn't so busy I'd write a small Rust program to do this now.