search

astral-sh / ruff

An extremely fast Python linter and code formatter, written in Rust.
https://docs.astral.sh/ruff
MIT License
30.79k stars 1.02k forks source link

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

Open carljm opened 1 month ago

carljm commented 1 month ago

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 commented 1 month ago

cc @MichaReiser @BurntSushi for opinions here

BurntSushi commented 1 month ago

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.