Turn on --document-private-items in CI cargo doc run?

[carljm]

If you don't use --document-private-items, then cargo doc won't do anything with doc comments in private modules or on private items; they can have all kinds of issues (e.g. link to nonexistent things) and CI won't catch it.

Given that our public docs use mkdocs, and our rustdoc comments are for our own internal maintenance use, not for documenting a public API, it might make more sense to have our CI use --document-private-items?

This will require a bit of work to clean up a bunch of existing problems in non-public doc comments that were never caught because we don't use --document-private-items.

One thing worth noting: even with --document-private-items, it's still a warning (which for our CI run means an error, since we set RUSTDOCFLAGS='-D warnings') for a public item's docs to link to a private item. I think this is a good thing.

[carljm]

cc @MichaReiser @BurntSushi for opinions here

[BurntSushi]

Just to make sure I understand here, this is just about a CI run that does a check that cargo doc --document-private-items actually works? I don't think I have a strong opinion on that personally, and your reasoning seems good to me. I very rarely use that flag though, so I don't have a ton of experience with it.