Open carljm opened 1 month ago
cc @MichaReiser @BurntSushi for opinions here
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.
If you don't use
--document-private-items
, thencargo 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 setRUSTDOCFLAGS='-D warnings'
) for a public item's docs to link to a private item. I think this is a good thing.