Skip to content

rustdoc: render doc(hidden) as a code attribute #151001

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
chojs23 wants to merge 3 commits into
base: main
Choose a base branch
from
+42 −30
Open

rustdoc: render doc(hidden) as a code attribute #151001

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
00c605f
rustdoc: render doc(hidden) as a code attribute
chojs23 Jan 12, 2026
fad92ca
Reexports show the 👻 indicator instead of an inline #[doc(hidden)] at…
chojs23 Jan 12, 2026
d88a903
show ghost for hidden extern crate
chojs23 Jan 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 0 additions & 4 deletions src/librustdoc/html/format.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1390,10 +1390,6 @@ impl clean::FnDecl {

pub(crate) fn visibility_print_with_space(item: &clean::Item, cx: &Context<'_>) -> impl Display {
fmt::from_fn(move |f| {
if item.is_doc_hidden() {
f.write_str("#[doc(hidden)] ")?;
}

let Some(vis) = item.visibility(cx.tcx()) else {
return Ok(());
};
Expand Down
4 changes: 4 additions & 0 deletions src/librustdoc/html/render/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1078,6 +1078,7 @@ fn assoc_type(
cx: &Context<'_>,
) -> impl fmt::Display {
fmt::from_fn(move |w| {
render_attributes_in_code(w, it, &" ".repeat(indent), cx)?;
write!(
w,
"{indent}{vis}type <a{href} class=\"associatedtype\">{name}</a>{generics}",
Expand Down Expand Up @@ -2915,6 +2916,9 @@ fn render_attributes_in_code(
prefix: &str,
cx: &Context<'_>,
) -> fmt::Result {
if item.is_doc_hidden() {
render_code_attribute(prefix, "#[doc(hidden)]", w)?;
}
for attr in &item.attrs.other_attrs {
let hir::Attribute::Parsed(kind) = attr else { continue };
let attr = match kind {
Expand Down
43 changes: 23 additions & 20 deletions src/librustdoc/html/render/print_item.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -340,15 +340,31 @@ fn item_module(cx: &Context<'_>, item: &clean::Item, items: &[clean::Item]) -> i
}

for (_, myitem) in &not_stripped_items[&type_] {
let visibility_and_hidden = |item: &clean::Item| match item.visibility(tcx) {
Some(ty::Visibility::Restricted(_)) => {
if item.is_doc_hidden() {
// Don't separate with a space when there are two of them
"<span title=\"Restricted Visibility\">&nbsp;🔒</span><span title=\"Hidden item\">👻</span> "
} else {
"<span title=\"Restricted Visibility\">&nbsp;🔒</span> "
}
}
_ if item.is_doc_hidden() => "<span title=\"Hidden item\">&nbsp;👻</span> ",
_ => "",
};

match myitem.kind {
clean::ExternCrateItem { ref src } => {
use crate::html::format::print_anchor;

let visibility_and_hidden = visibility_and_hidden(myitem);
write!(w, "<dt><code>")?;
Copy link
Member

@GuillaumeGomez GuillaumeGomez Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please move this into render_attributes_in_code so we don't write <dt><code> if there are no attributes.

render_attributes_in_code(w, myitem, "", cx)?;
match *src {
Some(src) => {
write!(
w,
"<dt><code>{}extern crate {} as {};",
"{}extern crate {} as {};",
visibility_print_with_space(myitem, cx),
print_anchor(myitem.item_id.expect_def_id(), src, cx),
EscapeBodyTextWithWbr(myitem.name.unwrap().as_str())
Expand All @@ -357,7 +373,7 @@ fn item_module(cx: &Context<'_>, item: &clean::Item, items: &[clean::Item]) -> i
None => {
write!(
w,
"<dt><code>{}extern crate {};",
"{}extern crate {};",
visibility_print_with_space(myitem, cx),
print_anchor(
myitem.item_id.expect_def_id(),
Expand All @@ -367,14 +383,15 @@ fn item_module(cx: &Context<'_>, item: &clean::Item, items: &[clean::Item]) -> i
)?;
}
}
write!(w, "</code></dt>")?
write!(w, "</code>{visibility_and_hidden}</dt>")?
}
clean::ImportItem(ref import) => {
let stab_tags =
import.source.did.map_or_else(String::new, |import_def_id| {
print_extra_info_tags(tcx, myitem, item, Some(import_def_id))
.to_string()
});
let visibility_and_hidden = visibility_and_hidden(myitem);
let id = match import.kind {
clean::ImportKind::Simple(s) => {
format!(" id=\"{}\"", cx.derive_id(format!("reexport.{s}")))
Expand All @@ -386,13 +403,13 @@ fn item_module(cx: &Context<'_>, item: &clean::Item, items: &[clean::Item]) -> i
"<dt{id}>\
<code>"
)?;
render_attributes_in_code(w, myitem, "", cx)?;
write!(
w,
"{vis}{imp}</code>{stab_tags}\
"{vis}{imp}</code>{visibility_and_hidden}{stab_tags}\
</dt>",
vis = visibility_print_with_space(myitem, cx),
imp = print_import(import, cx),
visibility_and_hidden = visibility_and_hidden,
)?;
}
_ => {
Expand All @@ -412,20 +429,7 @@ fn item_module(cx: &Context<'_>, item: &clean::Item, items: &[clean::Item]) -> i
}
_ => "",
};
let visibility_and_hidden = match myitem.visibility(tcx) {
Some(ty::Visibility::Restricted(_)) => {
if myitem.is_doc_hidden() {
// Don't separate with a space when there are two of them
"<span title=\"Restricted Visibility\">&nbsp;🔒</span><span title=\"Hidden item\">👻</span> "
} else {
"<span title=\"Restricted Visibility\">&nbsp;🔒</span> "
}
}
_ if myitem.is_doc_hidden() => {
"<span title=\"Hidden item\">&nbsp;👻</span> "
}
_ => "",
};
let visibility_and_hidden = visibility_and_hidden(myitem);

let docs = MarkdownSummaryLine(&myitem.doc_value(), &myitem.links(cx))
.into_string();
Expand Down Expand Up @@ -1849,7 +1853,6 @@ fn item_variants(
fn item_macro(cx: &Context<'_>, it: &clean::Item, t: &clean::Macro) -> impl fmt::Display {
fmt::from_fn(|w| {
wrap_item(w, |w| {
// FIXME: Also print `#[doc(hidden)]` for `macro_rules!` if it `is_doc_hidden`.
render_attributes_in_code(w, it, "", cx)?;
if !t.macro_rules {
write!(w, "{}", visibility_print_with_space(it, cx))?;
Expand Down
21 changes: 15 additions & 6 deletions tests/rustdoc-html/display-hidden-items.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,23 +7,30 @@
//@ has 'foo/index.html'
//@ has - '//dt/span[@title="Hidden item"]' '👻'

//@ has - '//*[@id="reexport.hidden_reexport"]/code' '#[doc(hidden)] pub use hidden::inside_hidden as hidden_reexport;'
//@ matchesraw 'foo/index.html' '(?s)<dt><code><div class="code-attribute">#\[doc\(hidden\)\]</div>pub extern crate .*?hidden_(?:<wbr>)?core;</code><span title="Hidden item">&nbsp;👻</span> </dt>'
Copy link
Member

@GuillaumeGomez GuillaumeGomez Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not supposed to have the #[doc(hidden)] attribute since there is the ghost.

#[doc(hidden)]
pub extern crate core as hidden_core;

//@ has - '//*[@id="reexport.hidden_reexport"]/span[@title="Hidden item"]' '👻'
//@ has - '//*[@id="reexport.hidden_reexport"]/code' 'pub use hidden::inside_hidden as hidden_reexport;'
#[doc(hidden)]
pub use hidden::inside_hidden as hidden_reexport;

//@ has - '//dt/a[@class="trait"]' 'TraitHidden'
//@ has 'foo/trait.TraitHidden.html'
//@ has - '//code' '#[doc(hidden)] pub trait TraitHidden'
//@ has 'foo/trait.TraitHidden.html' '//*[@class="rust item-decl"]//*[@class="code-attribute"]' '#[doc(hidden)]'
//@ has 'foo/trait.TraitHidden.html' '//*[@class="rust item-decl"]/code' 'pub trait TraitHidden'
#[doc(hidden)]
pub trait TraitHidden {}

//@ has 'foo/index.html' '//dt/a[@class="trait"]' 'Trait'
pub trait Trait {
//@ has 'foo/trait.Trait.html'
//@ has - '//*[@id="associatedconstant.BAR"]/*[@class="code-header"]' '#[doc(hidden)] const BAR: u32 = 0u32'
//@ has - '//*[@id="associatedconstant.BAR"]/*[@class="code-header"]/*[@class="code-attribute"]' '#[doc(hidden)]'
#[doc(hidden)]
const BAR: u32 = 0;

//@ has - '//*[@id="method.foo"]/*[@class="code-header"]/*[@class="code-attribute"]' '#[doc(hidden)]'
//@ has - '//*[@id="method.foo"]/*[@class="code-header"]' 'fn foo()'
#[doc(hidden)]
fn foo() {}
Expand All @@ -44,22 +51,24 @@ impl Struct {
}

impl Trait for Struct {
//@ has - '//*[@id="associatedconstant.BAR"]/*[@class="code-header"]' '#[doc(hidden)] const BAR: u32 = 0u32'
//@ has - '//*[@id="method.foo"]/*[@class="code-header"]' '#[doc(hidden)] fn foo()'
//@ has - '//*[@id="associatedconstant.BAR"]/*[@class="code-header"]/*[@class="code-attribute"]' '#[doc(hidden)]'
//@ has - '//*[@id="method.foo"]/*[@class="code-header"]/*[@class="code-attribute"]' '#[doc(hidden)]'
}
//@ has - '//*[@id="impl-TraitHidden-for-Struct"]/*[@class="code-header"]' 'impl TraitHidden for Struct'
impl TraitHidden for Struct {}

//@ has 'foo/index.html' '//dt/a[@class="enum"]' 'HiddenEnum'
//@ has 'foo/enum.HiddenEnum.html'
//@ has - '//code' '#[doc(hidden)] pub enum HiddenEnum'
//@ has 'foo/enum.HiddenEnum.html' '//*[@class="rust item-decl"]//*[@class="code-attribute"]' '#[doc(hidden)]'
//@ has 'foo/enum.HiddenEnum.html' '//*[@class="rust item-decl"]/code' 'pub enum HiddenEnum'
#[doc(hidden)]
pub enum HiddenEnum {
A,
}

//@ has 'foo/index.html' '//dt/a[@class="enum"]' 'Enum'
pub enum Enum {
//@ has 'foo/enum.Enum.html' '//*[@id="variant.A"]/*[@class="code-header"]/*[@class="code-attribute"]' '#[doc(hidden)]'
//@ has 'foo/enum.Enum.html' '//*[@id="variant.A"]/*[@class="code-header"]' 'A'
#[doc(hidden)]
A,
Expand Down
Loading