user0/rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Rollup merge of #146495 - fmease:rustdoc-erase-doc-priv-items-attr, r=GuillaumeGomez

Browse source 
rustdoc: Erase `#![doc(document_private_items)]`

I just found out about the existence of `#![doc(document_private_items)]`. Apparently it was added by PR rust-lang/rust#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 rust-lang/rust#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 rust-lang/rust#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](https://github.com/rust-lang/rust/issues?q=is%3Aissue+document_private_items)) complaining about the lint emission and the fact that GitHub code search doesn't yield any actual uses ([via](https://github.com/search?q=%2F%23%21%5C%5Bdoc%5C%28.*%3Fdocument_private_items%2F+language%3ARust&type=code&ref=advsearch)), 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.
This commit is contained in:
Stuart Cook 2025-11-11 21:09:33 +11:00 • committed by GitHub
commit 6487148d80
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 2 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

1
compiler/rustc_passes/messages.ftl
View file

@ -219,7 +219,6 @@ passes_doc_test_unknown_passes =
unknown `doc` attribute `{$path}`
.note = `doc` attribute `{$path}` no longer functions; see issue #44136 <https://github.com/rust-lang/rust/issues/44136>
.label = no longer functions
.help = you may want to use `doc(document_private_items)`
.no_op_note = `doc({$path})` is now a no-op
passes_doc_test_unknown_plugins =

1
compiler/rustc_passes/src/errors.rs
View file

@ -347,7 +347,6 @@ pub(crate) struct DocTestUnknownSpotlight {
#[derive(LintDiagnostic)]
#[diag(passes_doc_test_unknown_passes)]
#[note]
#[help]
#[note(passes_no_op_note)]
pub(crate) struct DocTestUnknownPasses {
pub path: String,

1
compiler/rustc_span/src/symbol.rs
View file

@ -899,7 +899,6 @@ symbols! {
doc_primitive,
doc_spotlight,
doctest,
document_private_items,
dotdot: "..",
dotdot_in_tuple_patterns,
dotdoteq_in_patterns,

8
src/librustdoc/core.rs
View file

@ -416,14 +416,6 @@ pub(crate) fn run_global_ctxt(
);
}
// Process all of the crate attributes, extracting plugin metadata along
// with the passes which we are supposed to run.
for attr in krate.module.attrs.lists(sym::doc) {
if attr.is_word() && attr.has_name(sym::document_private_items) {
ctxt.render_options.document_private = true;
}
}
info!("Executing passes");
let mut visited = FxHashMap::default();

2
tests/rustdoc-ui/deprecated-attrs.rs
View file

@ -4,14 +4,12 @@
//~^ ERROR unknown `doc` attribute `no_default_passes`
//~| NOTE no longer functions
//~| NOTE see issue #44136
//~| HELP you may want to use `doc(document_private_items)`
//~| NOTE `doc(no_default_passes)` is now a no-op
//~| NOTE `#[deny(invalid_doc_attributes)]` on by default
#![doc(passes = "collapse-docs unindent-comments")]
//~^ ERROR unknown `doc` attribute `passes`
//~| NOTE no longer functions
//~| NOTE see issue #44136
//~| HELP you may want to use `doc(document_private_items)`
//~| NOTE `doc(passes)` is now a no-op
#![doc(plugins = "xxx")]
//~^ ERROR unknown `doc` attribute `plugins`

6
tests/rustdoc-ui/deprecated-attrs.stderr
View file

@ -10,22 +10,20 @@ LL | #![doc(no_default_passes)]
| ^^^^^^^^^^^^^^^^^ no longer functions
|
= note: `doc` attribute `no_default_passes` no longer functions; see issue #44136 <https://github.com/rust-lang/rust/issues/44136>
= help: you may want to use `doc(document_private_items)`
= note: `doc(no_default_passes)` is now a no-op
= note: `#[deny(invalid_doc_attributes)]` on by default
error: unknown `doc` attribute `passes`
--> $DIR/deprecated-attrs.rs:10:8
--> $DIR/deprecated-attrs.rs:9:8
|
LL | #![doc(passes = "collapse-docs unindent-comments")]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ no longer functions
|
= note: `doc` attribute `passes` no longer functions; see issue #44136 <https://github.com/rust-lang/rust/issues/44136>
= help: you may want to use `doc(document_private_items)`
= note: `doc(passes)` is now a no-op
error: unknown `doc` attribute `plugins`
--> $DIR/deprecated-attrs.rs:16:8
--> $DIR/deprecated-attrs.rs:14:8
|
LL | #![doc(plugins = "xxx")]
| ^^^^^^^^^^^^^^^ no longer functions