Lint doc comments on private items

[llogiq]

Since we recently started targeting comments, recently someone asked why their doc comments don't show up for a private function.

We could lint and suggest either making the function public (if intended) or make the comment a normal line comment.

I'm not sure if this should warn, though.

[mcarton]

I'm not sure if this should warn, though.

Nah. I like to use that trick to generate private doc. I think this is something cargo doc should support.

[llogiq]

OK, but that's something a well-seasoned dev would attempt, and clippy also tries to help newbies (and forgetting pub is at least as likely than documenting private functions just because, then wondering why the docs fail to show).

[shepmaster]

Conversely, I'd like a lint to warn when a private function is not documented.

Since rustdoc's behavior around documenting private items has changed greatly (e.g. binaries include them by default, you can use --document-private-items) perhaps this issue should be closed or repurposed.

[flip1995]

@shepmaster this lint already exists: missing_docs_in_private_items, but has to be enabled explicitely. (Also it will lint on all private items, not only functions.)

[shepmaster]

this lint already exists

Ah, thanks! I only looked for an official rustdoc lint.

[flip1995]

See also #5736

[BatmanAoD]

I agree this should be closed.