rustdoc: show the descriptions of traits’ implementations if any

[IvanUkhov]

Right now if one adds additional information to an implementation of a trait’s method, that information is not shown in the output of rustdoc. For instance, the implementation of Drop for Rc has an elaborate description with an example; however, this information is not accessible to the readers.

Regards,
Ivan

[steveklabnik]

This used to work. @alexcrichton did you change this?

[alexcrichton]

I do vaguely remember intentionally removing this because it was way too noisy, but I have a feeling that we just blanket inlined documentation instead of only displaying documentation that was explicitly written. I think it'd be fine to implement this, and at the very least we could just browse around the docs and see how they looked.

[bluss]

This is the same issue as #24838.

Note that you can document the impl by putting the doc on top of the impl block now. (Please don't remove that! 😄)

[leoyvens]

Many impls are documented with the docs inside the methods (all in std I think), it's quite a loss not to display them. If it's noisy, maybe collapse them by default? Things like impl<A, E, V> FromIterator<Result<A, E>> for Result<V, E> where V: FromIterator<A> need visible documentation. If something implements Default, what is the Default? Documentation for impls is just as important as for methods, IMO.

[erip]

I agree with @leodasvacas - I'm having a huge problem with this right now because I have a trait that is virtually an interface and can provide no information about how its used when implemented by other structs.

[bluss]

@erip You can provide something as noted above, the doc comment above the impl block will be shown, and you can use that until this issue is fixed.

[erip]

@bluss Yes, but that is a little clumsy and it doesn't maintain the nice layout expected by rustdocs. I'll use it for now, but I hope this doesn't get overlooked - I notice it's been open for at least 6 months.