CI tests running rustdoc with `--document-private-items --document-hidden-items` on `std`?

[steffahn]

I recently broke the command RUSTDOCFLAGS='--document-private-items --document-hidden-items' x doc library/std, see #87842, which demonstrates that CI doesn’t test rustdoc on the standard library with these flags. In effect, code with broken intra doc links in or other issues with doc(hidden) items (and probably also for private items?) aren’t detected and can be merged into master. Maybe we want to add a test for it? Possibly it’s even true that normal x doc library/std will always succeed if the one with --document-private-items --document-hidden-items does so we wouldn’t even need to test both with and without those flags? (Correct me if I’m wrong on that last point.)

@rustbot label T-infra, A-docs, A-testsuite, C-enhancement

[jyn514]

@steffahn it seems weird that we'd support this - why would you run document-hidden-items at all?

[steffahn]

why would you run document-hidden-items at all?

@jyn514 Because it’s super useful when you’re trying to understand implementation details. I’ve recently been contributing on specializations of iterators involving traits like TrustedRandomAccess which is public but doc(hidden). The broken link intra doc link actually hindered my progress reviewing a PR for a few hours until I realized that I could add -Arustdoc::broken-intra-doc-links. But in any case, it’s mostly just an argument of: Hidden items can and do have doc comments and it can be useful to render them (with --document-private-items), so why shouldn’t we make sure to keep them working?

Note that the PR mentioned in #87842 didn’t even modify the comment in question that got broken but instead just modified code in the module and with the effect of subsequently removing an import, in turn breaking the hidden doc comments. It’s hard to consistently keep those doc comments clean/working without an automated test, IMO.

[jyn514]

Gotcha - this seems reasonable to me, but it couldn't replace building without those flags because they're not actually tested, x.py just builds them directly for upload to static.rlo. But it should be pretty cheap to run it twice since it's just the libraries.

[jyn514]

Mentoring instructions: looks like @ChrisDenton already added --document-private-items, so we just need to add --document-hidden-items to this command and we can close the issue :)

rust/src/ci/docker/host-x86_64/mingw-check/Dockerfile

Line 49 in b685242

RUSTDOCFLAGS="--document-private-items" python3 ../x.py doc --stage 0 library/test && \