Types made public via associated types are not documented

[nagisa]

Given following code:

mod raspberry {
    pub struct Banana;
}

pub struct Peach;

pub trait Apple {
    type Juice;
}

impl Apple for Peach {
    type Juice = raspberry::Banana;
}

The generated documentation will not include documentation for <Peach as Apple>::Juice.

[cuviper]

Isn't this true of any pub-in-private use? i.e. not just associated types, but also parameters, return values, trait constraints, etc. There's no publicly reachable path to Banana, so it don't get docs.

However, if you put doc comments on the type Juice, it does generate documentation there.

[jyn514]

@nagisa do you still think this is a bug? I'm not sure what rustdoc could do differently here.

[nagisa]

Yeah, I still consider it a bug, provided the original example behaves as it did when this was initially reported. It effectively fails to generate documentation for a public item, which is a major issue if the Banana type happens to be important in some way.

I also think it is an important bug to resolve because it is fairly easy to design a library around a concept such as this without ever noticing that there will be consequences in terms of generated documentation. (Who really checks the generated documentation before publishing crates?)

There's no publicly reachable path to Banana, so it don't get docs.

<Peach as Apple>::Juice is one such public path. As in, anywhere in the code specifying this will give you a Banana, even if you cannot refer to it in a more direct way. At the type system level I believe it will also directly refer to Banana as well, as opposed to considering it an associated type, with all of the relevant caveats.

Parameters and return values are slightly different as you cannot explicitly refer to those types elsewhere in the code. As thus I consider them of significantly lower importance. Public-private arguments are also used for privacy hacks, so it isn't as clear whether those ought to be documented.

[camelid]

Totally off-topic: I want to see more of this code! It's mouthwatering ;) 🍓