needless_doctest_main yields false positive with proc macros

[Rantanen]

Clippy version: 0.0.212 (e979eb4 2019-10-17)

Clippy warns that the fn main() {} is not needed in the following doctest:

https://github.com/Rantanen/intercom/blob/45837a4d77c340c9cb8cf45142843198a80a82b6/intercom/src/lib.rs#L12-L36

However removing that will end up with doctest wrapping the whole thing in a function, which results in the com_library!(Calculator); becoming a statement - something that is not allowed for (at least that) proc macro.

I feel like this is enough of a niche case that there's no real need to fix it. A note could be added to the Known problems section of the lint.

[Rantanen]

Okay this was a bit more annoying than I thought. The fact that I had the issue on crate level documentation prevented me from using #[allow(clippy::needless_doctest_main)] on that specific doctest. The attribute inside the doctest did nothing while outside the only way I could have put it on the "item" was a crate-wide #![allow(...)].

In the end I found out that the check is a rather simple one:

rust-clippy/clippy_lints/src/doc.rs

Lines 347 to 351 in 850ad52

	fn check_code(cx: &LateContext<'_, '_>, text: &str, span: Span) {
	if text.contains("fn main() {") {
	span_lint(cx, NEEDLESS_DOCTEST_MAIN, span, "needless `fn main` in doctest");
	}
	}

My workaround involves turning the main function into fn main() -> () {}, which results in Clippy not discovering it.

Edit: I wanted to document this in the doctest itself so I wouldn't wonder why I'd include the -> () in the main declaration. While doing this, I made the mistake of writing fn main() {} in the comments within the doctest and suddenly clippy started yelling at me again... :)

[llogiq]

Yeah the check is at the moment just text-based. And detecting proc macros that expand to items is somewhat harder.

A simple trick that would work is

///# fn main 
///# // keep this to quell `needless_doctest_main` warning
///#(){}