Rust-clippy: doc_markdown should ignore plain URLs

[behnam]

The doc_markdown rule is expected to search the plain text of a Markdown content, and should exclude non-plain-text parts, like code blocks and URLs.

Plain URLs (not labeled links or URLs in brackets) are core components of markdown and should be respected as URLs and not plain text.

From the perspective of what's going on in practice: when implementing a spec in code, it's very common to put a plain URL link to the spec, as a point of reference. These URLs are most of the time very well self-descriptive and there's no need for extra work to label them.

Example: all the URLs like http://www.unicode.org/reports/tr9/... here: https://github.com/servo/unicode-bidi/blob/master/src/explicit.rs

Based on these, clippy should no warn about any formatting issues about pain URLs, specially the backtick requirement.

Also reported back in Feb: https://github.com/Manishearth/rust-clippy/issues/1558

[Manishearth]

This will probably get fixed by https://github.com/Manishearth/rust-clippy/pull/1799

cc @mcarton

Up till now we had a thing that would kind of parse a subset of markdown.

[mcarton]

No it won't. A raw link like this is considered text in CommonMark. If you really want a raw link you need </> around it. See the spec, specifically example 580.

And those links are not rendered by rustdoc itself anymore with --enable-commonmark, so clippy really is in its right to lint here.

[Manishearth]

We should probably _catch_ raw links and report them.

[behnam]

Yeah, if rustdoc won't (under CM) linkify them, then it makes sense to treat them as text, and even report them.

[behnam]

Actually, looks like the doc_markdown rule (clippy v0.0.140) still warns on URL components for Autolinks (when URL is surrounded by angle brackets)!

warning: you should put `Reordering_Resolved_Levels` between ticks in the documentation
  --> src/deprecated.rs:23:42
   |
23 | /// <http://www.unicode.org/reports/tr9/#Reordering_Resolved_Levels>
   |                                          ^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: #[warn(doc_markdown)] on by default
   = help: for further information visit https://github.com/Manishearth/rust-clippy/wiki#doc_markdown

warning: you should put `Directional_Formatting_Characters` between ticks in the documentation

[mcarton]

Ok, this I can fix.