Rustdoc generates docs for hidden methods in impls

0de2c48
Opened by Patrick Reisert at 2024-12-21 05:02:38

I've seen #34025, but in the following case rustdoc still generates documentation for hidden() in the impl Bar for Foo (but as tymethod instead of method). It works correctly if hidden() is also marked as hidden in the trait definition.

pub struct Foo;

pub trait Bar {
    fn test();
    fn hidden();
}

impl Bar for Foo {
    fn test() {}
    #[doc(hidden)] fn hidden() {}
}

rustc -V: rustc 1.13.0-nightly (e9bc1bac8 2016-08-24)

  1. Current status: Still a problem. Rustdoc doesn't scan the visibility of items inside a trait implementation, and in fact doesn't even check against a trait definition when printing an implementation. This leads to odd situations where if you have the #[doc(hidden)] on the definition instead, the implementation still prints the method!

    image

    This is because the pass in rustdoc that strips out private or hidden items doesn't check "tymethods" for visibility at all:

    https://github.com/rust-lang/rust/blob/248745ab0c67c86b7ef810d22a386b005c9a093b/src/librustdoc/passes/mod.rs#L249-L250

    And the part that renders the final impl onto the page doesn't check visibility either.

    Looking at your sample and the code again, i think i can see what's happening:

    1. The strip-hidden pass looked at the trait definition, saw that both methods were visible, and left them in.
    2. The pass looked at the implementation, saw that one method was #[doc(hidden)], and stripped that method from that impl.
    3. The renderer looked at the impl, saw one method that was still present, and rendered it.
    4. The renderer saw that the impl had a trait on it, looked in the trait, saw a method that wasn't in the impl, and rendered that.

    That partially explains why you need #[doc(hidden)] on both for the method to be hidden, but it also confuses me after seeing that "tymethods have no control over privacy" thing. I bet #[doc(hidden)] is processed in a different place, but at least this can explain what's going on.

    QuietMisdreavus at 2018-11-05 02:15:26

  2. I've just stumbled upon this GitHub issue. I am actually convinced that one shouldn't be allowed to place #[doc(hidden)] on trait impl items since it doesn't really make sense to me from a conceptional / semantic point of view: When you are impl'ing a trait (and the impl block is not #[doc(hidden)] which would be absolutely fine), you promise that you fully conform to the trait's API. Why would you want to hide part of the API when people can just look up the trait's documentation and find the supposedly hidden method?

    For context, I actually went so far as to implement a lint for this (#96008, #97208) but I later had to remove it (#98336) basically because in some cases it actually does get hidden (#96890).

    Just FYI for people stopping by reading this issue.

    León Orell Valerian Liehr at 2022-07-27 15:01:54