Restore trait impl docs

[pierzchalski]

Currently, documentation on methods in trait implementations doesn't get rendered. This changes that; trait implementations have all documentation associated with impl items displayed (documentation from the trait definition is ignored).

Fixes #24838
Fixes #26871

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @steveklabnik (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[steveklabnik]

Love this change conceptually, not great with rustdoc's codebase yet. r? @alexcrichton

[mitaa]

manual trait implementations have their documentation displayed, however derived traits don't.

I think it would make sense to instead only document(..) such impl-items if they actually have doc-comments (item.doc_value().is_some())

Then you could remove the render_docs: bool parameter and instead change the behaviour based on link: AssocItemLink.

[mitaa]

Could you also add some tests in src/test/rustdoc/?
(you can run these tests with, for example,make check-stage1-rustdocck)

[GuillaumeGomez]

What the hell is happening in commits messages in here?! XD

[mitaa]

and instead change the behaviour based on link: AssocItemLink.

Actually, I think the current match on AssocItemLink in doctraititem could be just removed (and the if guard converted to a normal if..) since html::render::document already checks for item.doc_value().is_some() (it would render stability attributes too, but I think that's not really a problem).

So the only necessary change would be to make here.

[alexcrichton]

I'm on board with everything @mitaa has mentioned :)

[pierzchalski]

Applied both of @mitaa's suggestions. Currently this means derived implementations also print any associated docs. Is that an issue?

@GuillaumeGomez I don't know what you're talking about :D
For future reference, I force-pushed a clean branch because @mitaa's suggestions were basically a re-write of what I'd done (and also because I prefer to rebase off master than merging it in). Is that an acceptable practice for Rust PRs, or would a bunch of reversions/merges be preferable?

[mitaa]

Currently this means derived implementations also print any associated docs. Is that an issue?

I would assume that they don't have any 😄
(also from looking at the source just now it doesn't look that way)

For future reference, I force-pushed a clean branch because @mitaa's suggestions were basically a re-write of what I'd done (and also because I prefer to rebase off master than merging it in). Is that an acceptable practice for Rust PRs, or would a bunch of reversions/merges be preferable?

Yes, that's completely fine.

[pierzchalski]

@mitaa I'm looking at the docs (well, what make docs outputs), and I'm seeing some weird behaviour. For instance on the derived Clone impls for Option and Result, the required method clone has no docblock but the provided method clone_from does have one, even though they both have docs in the source for Clone. Turns out this also happens on manual trait impls.

I've updated the test to demonstrate the intended vs. actual behaviour, and now I'm hunting through html/render.rs and clean/mod.rs looking for why provided methods get the "doc" attribute of their definition but manual methods don't (which is what I'm guessing is causing the issue).

[mitaa]

Nice catch!

For non-overridden default methods we actually render the method of the trait itself (which obviously has the doc attribute).
https://github.com/pierzchalski/rust/blob/restore_trait_impl_docs/src/librustdoc/html/render.rs#L2555-L2581

doctraititem probably needs a ~is_default_item: bool argument after all.

[mitaa]

Well, that coupled with checking that link == Anchor::GotoSource(..). (we still want to show the docs on the trait itself)

[pierzchalski]

Done.

Also, it looks like the AssocItemLink::Anchor test was unnecessary since doctraititem is only called to render trait impls, and doesn't affect the rendering of trait definitions including default items.

[alexcrichton]

@bors: r+ ec5e0f8

Thanks @pierzchalski!