Split `missing_docs_in_private_items` into various lints

[jhpratt]

Would it be feasible and acceptable to split missing_docs_in_private_items into a few different lints? I find myself quite frequently adding #[allow] to enum variants and struct fields, in large part because the naming is typically self-explanatory. Even splitting the lint in two (fields/variants and everything else) would be incredibly useful for me, and would avoid cluttering declarations with unnecessary (imo) #[allow] attributes.

Having different lints for modules and top-level crate documentation would also be great, but are less important to me.

[jhpratt]

A quick rg and tokei on a project of mine (admittedly with a large number of structs) shows that I have #[allow(clippy::missing_docs_in_private_items)] 64 times out of 1387 total lines of Rust code (4.6% of all lines). All 64 are on enum variants and struct fields.

If this is something that is desired, I'd be interested in contributing once I get some free time.

[flip1995]

Maybe even better: Don't split it, but make it configurable, so that you can configure it to only warn on functions for example.

[jhpratt]

That could certainly work, and would be backwards-compatible as well.

[jhpratt]

Another situation I've found myself allowing the lint regularly is statics, consts, structs, etc. that are only used within the function they're defined in.

[flip1995]

I think we should not lint at all on definitions inside a function.

[pvdrz]

On bindgen we do this hack to keep reusable code documented by marking it as public but putting it inside a module that's only public if compiled with a certain feature: https://github.com/rust-lang/rust-bindgen/blob/a7ff8e136027c9542f65eca97a7ff3c0b870518d/bindgen/lib.rs#L36-L50

This has the undesired effect of not being able to detect unused items because they are public.

If this lint could be configured to detect missing docs in pub(crate) items, we could remove this hack and remove the downside of not detecting unused code.

Let me know if this would be a reasonable change and I will start working on it.

[flip1995]

I could see a config option, that you can set to specify if the lint should lint on all private items or only on crate items. All private items should be the default though. Let me know if you need help implementing this. clippy_lints/src/utils/conf.rs is a good starting point to look at for adding config options.