Add new lint doc_include_without_cfg

[GuillaumeGomez]

It's becoming more and more common to see people including markdown files in their code using doc = include_str!("..."), which is great. However, often there is no condition on this include, which is not great because it slows down compilation and might trigger recompilation if these files are updated.

This lint aims at fixing this situation.

changelog: Add new lint doc_include_without_cfg

[rustbot]

r? @blyxyas

rustbot has assigned @blyxyas.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[blyxyas]

Very very good PR, just a nit.
I'll open the FCP now, because I'm sure this review cycle will go fast

[blyxyas]

I've looked for way to remove this snippet, but as the include_macro expands before we check the #[doc] attribute, I don't think it's possible.

[GuillaumeGomez]

Adding a comment will still be a good improvement. :)

[blyxyas]

Maybe a "we cannot remove this because a #[doc = include] can occupy several lines" comment would be useful here, I also checked removing these, but it doesn't seem possible =^w^=

[blyxyas]

Could you add a test for one of the other ways that the #[doc] attribute can behave?

#![doc(html_playground_url = "https://playground.example.com/")]

And such

[GuillaumeGomez]

Added code comments and added extra tests.

[samueltardieu]

@GuillaumeGomez Using macros may trigger false positives (found by looking at the lintcheck diff):

macro_rules! tst {
    ($(#[$attr:meta])*) => {
        $(#[$attr])*
        fn main() {
            println!("Hello, world!");
        }
    }
}

tst!{
    /// This is a test with no included file
}

will trigger with:

warning: included a file in documentation unconditionally
  --> /tmp/t.rs:3:11
   |
3  |           $(#[$attr])*
   |             ^^^^^^^^ help: use `cfg_attr(doc, doc = "...")`: `#[cfg_attr(doc, $attr)]`
...
10 | / tst!{
11 | |     /// This is a test with no included file
12 | | }
   | |_- in this macro invocation

[GuillaumeGomez]

Great catch! If the attribute is generated from a macro, the lint now ignores it.

[GuillaumeGomez]

Fixed formatting...

[samueltardieu]

Great. The new hits in clap and bumpalo look legitimate, however it looks like hits in socket2 might be false positives.

[GuillaumeGomez]

They were false positives. So we're forced to check that the snippet is indeed include_str!. Fun times. ^^'