Missing docs lint ineffectual in test builds

The missing_docs lint does not do anything in test builds. Minimal code example:

#![cfg_attr(test, deny(missing_docs))]

To reproduce, make a new crate, replace src/lib.rs with the above code, and run cargo test. The command will run successfully. I would expect the command to report a “missing documentation for crate” compile error.

As for the cause, my wild guess is some sort of interaction between cfg(test) and which items are detected as public.

1. Triage: as a slightly more full example, this crate will compile with --test, but not compile without it:

   #![deny(missing_docs)]
   
   #[test]
   fn foo() {}
   
   fn lol() {}
   
   fn main() {}
   

   Steve Klabnik at 2016-06-06 21:18:46

2. Triage: no change

   Steve Klabnik at 2018-10-31 14:49:42

3. This is also an issue for editors that use cargo check --profile=test in order to include tests in the check. This means the lint doesn't ever fire in the editor.

   It looks like the check was added in https://github.com/rust-lang/rust/commit/4a5d887b58ff9833a968e7a0d28282b915e01de8. I suspect the reasoning is that code inside a cfg(test) block should not be checked for missing docs, which makes sense. I think it would be nicer to allow missing_docs to run with --test, but to not check any block/module/item that is marked with cfg(test). Unfortunately, I think that is very difficult or impossible to do. 😦

   Eric Huss at 2020-09-26 19:22:12

4. I suspect the reasoning is that code inside a cfg(test) block should not be checked for missing docs, which makes sense.

   Doesn't missing-docs only apply to public items? In which case it shouldn't trigger very often for items gated by cfg(test) since those are rarely public. And if they are, I would argue it's not hard to add #[allow(missing_docs)] or actually document that public item.

   I would be in favor of simply removing this corner case, i.e. check for missing-docs with --profile=test and do not try to be smart by avoiding items gated by cfg(test) since false positives should be rare (of course if that assumption is wrong, then this last part doesn't hold).

   Julien Cretin at 2024-09-30 13:35:30