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]

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. ^^'

[blyxyas]

I thought I had already approved this! ❤️ 🌈

We'll have to wait until the FCP is sorted out, seems that we're having some problems with hover documentation.

[GuillaumeGomez]

"Hover documentation"? I rewrote the lints page recently so maybe it's something I broke. Do you have an issue or a link so I can know what's wrong to fix it by any chance?

[blyxyas]

There's not a really way to fix it because it's a Rust Analyzer issue (hover documentation as in when you hover your mouse on the IDE)

Here's the FCP: https://rust-lang.zulipchat.com/#narrow/channel/257328-clippy/topic/FCP.20doc_include_without_cfg
And here's the Rust Analyzer issue on hover documentation for cfg_attr: rust-lang/rust-analyzer#18444

[GuillaumeGomez]

Ah I see. We can always make it allow by default if that makes it better. But let's see what clippy and r-a people think about it. 👍

[blyxyas]

LGTM! Could you make it pedantic?

https://rust-lang.zulipchat.com/#narrow/channel/257328-clippy/topic/FCP.20doc_include_without_cfg/near/482239356

[GuillaumeGomez]

Sure, done!

[GuillaumeGomez]

And CI passed. ~o~

[blyxyas]

Oh, and I forgot to mention: Could you also squash those 6 commits?

[GuillaumeGomez]

Done as well.