Check hidden/private items documentation in `rustdoc`

[ojeda]

Checking hidden/private items in rustdoc can be useful even if no docs are generated/displayed for them. For instance to detect broken intra-doc links there: someone may try to link something that didn't exist, for instance because there was a typo, or the docs became outdated, etc.

It is also nice when something is made public or un-hidden, or when the docs are copy-pasted to somewhere else, i.e. they would have a higher chance of working. Put another way, not checking means that the hidden/private items are, in a sense, less strict.

The fact that they are not checked can be surprising on its own. For instance, there was a brief period of time in 1.92's nightlies when checking actually took place by mistake [1][2], which made @BennoLossin send a fix for it, wondering why previous versions didn't catch it [3].

This can be worked around by doing two passes (i.e. one for checking, and one for the actual generation) with the --document-{hidden,private}-items flags (suggested by Guillaume). However, that requires two passes where one (the bigger one, in fact) will be simply discarded.

A related feature that can cover this one for some projects is the "Runtime toggle for private/hidden items documentation (and /* private fields */)" one, i.e. if there was a runtime toggle to see the private/hidden items, then the docs for those would of course have been checked already even if most users do not see/read them. That feature on its own is something that would be quite interesting [4].

[1] #147153 (comment)
[2] #147809
[3] https://lore.kernel.org/all/20251016211740.653599-1-lossin@kernel.org/T/
[4] #149106

Cc @GuillaumeGomez @fmease @lolbinarycat

@rustbot label T-rustdoc
@rustbot label A-intra-doc-links
@rustbot label A-rust-for-linux

[GuillaumeGomez]

The reason we don't do it by default is simply to reduce noise. If you don't build docs for private/hidden items, you don't care if their links are valid or not. But with the approach I suggested in #149106, I think it'll cover this issue as well in your case?

[ojeda]

It is good to reduce noise, and some projects may not care, but I don't think it is generally true that everyone doesn't care. It may e.g. spot outdated documentation and the other benefits I mention above.

By the way, to clarify, it is not just about the intra-doc links or links in general, i.e. rustdoc may check in the future other things too (e.g. typos against a dictionary/spellchecker/AI if that is not yet the case).

And, yeah, the toggle feature would cover this, i.e. that is what I meant above since if we have a toggle it means we have to generate docs anyway, and thus I assume we would get the checking done.

[bugadani]

The reason we don't do it by default is simply to reduce noise. If you don't build docs for private/hidden items, you don't care if their links are valid or not. But with the approach I suggested in #149106, I think it'll cover this issue as well in your case?

I don't think it is generally true that everyone doesn't care

I think that if we didn't care about pivate documentation, we wouldn't write private documentation. It's useful for a project's maintainers, and links in that documentation are useful for navigation using the IDE. Whether that documentation gets rendered or not is a more user-facing question.