rustdoc: Erase #![doc(document_private_items)]

[fmease]

I just found out about the existence of #![doc(document_private_items)]. Apparently it was added by PR #50669 back in 2018 without any tests or docs as a replacement for some specific forms of the removed #![doc(passes)] / #![doc(no_default_passes)].

However, rustc and rustdoc actually emit the deny-by-default lint invalid_doc_attributes for it (but if you allow it, the attribute does function)! To be more precise since PR #82708 (1.52, May 2021) which introduced lint invalid_doc_attributes, rust{,do}c has emitted a future-incompat warning for this attribute. And since PR #111505 (1.78, May 2024) that lint is deny by default. I presume nobody knew this attribute existed and thus it was never allowlisted.

Given the fact that since 2021 nobody has ever opened a ticket (via) complaining about the lint emission and the fact that GitHub code search doesn't yield any actual uses (via), I'm led to believe that nobody knows about and uses this attribute.

I don't find the existence of this attribute to be justified since in my view the flag --document-private-items is strictly superior: In most if not all cases, you don't want to "couple" your crate with this "mode" even if you gate it behind a cfg; instead, you most likely want to set this manually at invocation time, via a build config file like .cargo/config.toml or via a command runner like just I'd say.

Because of this I propose to wipe this attribute from existence. I don't believe it's worth cratering this (i.e., temporarily emitting a hard error for this attribute and running crater) given the fact that it's been undocumented since forever and led to a warning for years.

[rustbot]

r? @notriddle

rustbot has assigned @notriddle.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[fmease]

@rfcbot merge

[rust-rfcbot]

Team member @fmease has proposed to merge this. The next step is review by the rest of the tagged team members:

• @GuillaumeGomez
• @Manishearth
• @Nemo157
• @aDotInTheVoid
• @camelid
• @fmease
• @jsha
• @lolbinarycat
• @notriddle

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.