False positive unused_attributes lint on doc(hidden) attribute on associated type

[dtolnay]

The warning added by #96008 claims that doc(hidden) on an impl item is ignored by rustdoc, but it isn't necessarily.

The warning says:

whether the impl item is `doc(hidden)` or not entirely depends on the corresponding trait item

which is not true in the following repro:

pub trait Trait {
    type A;
    type B;
}

pub struct Struct;

impl Trait for Struct {
    type A = [(); "interesting type".len()];
    #[doc(hidden)]
    type B = [(); "nasty uninteresting type".len()];
}

$ cargo check
warning: `#[doc(hidden)]` is ignored on trait impl items
  --> src/lib.rs:10:5
   |
10 |     #[doc(hidden)]
   |     ^^^^^^^^^^^^^^ help: remove this attribute
   |
   = note: `#[warn(unused_attributes)]` on by default
   = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
   = note: whether the impl item is `doc(hidden)` or not entirely depends on the corresponding trait item

This warning is a false positive. Rustdoc does pay attention to this attribute. For the code above, the rendered documentation of Struct and Trait looks like:

After removing the supposedly unused doc(hidden) attribute and rendering again, the "nasty uninteresting type" that we wanted not shown is going to get rendered on both pages:

(@fmease @lcnr)

Meta

rustc --version --verbose:

rustc 1.62.0-nightly (88860d547 2022-05-09)
binary: rustc
commit-hash: 88860d5474a32f507dde8fba8df35fd2064f11b9
commit-date: 2022-05-09
host: x86_64-unknown-linux-gnu
release: 1.62.0-nightly
LLVM version: 14.0.1

[fmease]

My bad, I did not notice that at all 😳. I can adjust the lint once it's decided how we are going to proceed with my changes in general (see / blocked on #96008 (comment)).

@rustbot claim

[fmease]

In summary, #[doc(hidden)] on methods in trait impl blocks does not lead to any visual changes in the documentation whereas on associated types and constants, it hides the implementation (or “the thing to the right of the =”).

This weirdly deviates from my (former) personal mental model of how #[doc(hidden)] is supposed to work and be used. As far as I know, in all other cases, it leads to items, impl blocks, fields (“names” or “declarations”) not being shown. Here, however, the “name” keeps being shown, only the “value” is hidden. Hiding an inherent assoc item for example, hides the item completely. “Hiding” a trait impl item is, in my opinion, currently handled inconsistently by rustdoc and shouldn't lead to any visual changes (or rather “shouldn't be allowed”).

Out of curiosity, @ dtolnay, how / why do you use this feature? Do you use it to reduce visual clutter?

Edit: Ah, well, I overlooked the top right picture. So in some cases the item is indeed entirely hidden, not just the value.

[fmease]

Zulip discussion

[fmease]

Should I remove the lint entirely or should I adjust #[doc(hidden)]?

[SergioBenitez]

Just wanted to add that this is also affecting rocket, but in a different way:

impl<'a> Origin<'a> {
    /// The root: `'/'`.
    #[doc(hidden)]
    pub const ROOT: Origin<'static> = Origin::const_new("/", None);
}

   --> core/http/src/uri/origin.rs:119:5
    |
119 |     #[doc(hidden)]
    |     ^^^^^^^^^^^^^^ help: remove this attribute
    |
    = note: `#[warn(unused_attributes)]` on by default
    = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
    = note: whether the impl item is `doc(hidden)` or not entirely depends on the corresponding trait item

The const isn't there at all without the doc(hidden):

In summary, #[doc(hidden)] on methods in trait impl blocks does not lead to any visual changes in the documentation whereas on associated types and constants, it hides the implementation (or “the thing to the right of the =”).

Based on the above, this isn't correct: it actually hides the entire thing, at least for associated constants.

[fmease]

In your case, it's inherent associated items being accidentally flagged which is #97205 which was closed by #97208 meaning the most recent nightly should not have your issue anymore. Sorry for the inconvenience. The longer I look this lint, the less I like it.