Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

rustdoc should indicate when a doc was inherited from a trait. #11991

Closed
jakerr opened this issue Feb 2, 2014 · 2 comments
Closed

rustdoc should indicate when a doc was inherited from a trait. #11991

jakerr opened this issue Feb 2, 2014 · 2 comments
Labels
E-easy Call for participation: Easy difficulty. Experience needed to fix: Not much. Good first issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@jakerr
Copy link
Contributor

jakerr commented Feb 2, 2014

When a specific implementation of a trait isn't commented the docs are inherited from the trait. It would be great if this fact was called out.

An example of why this is useful:

The current doc for Rc has:

  • impl Clone for Rc
    • fn clone(&self) -> Rc
      • Returns a copy of the value. The contents of owned pointers are copied to maintain uniqueness, while the contents of managed pointers are not copied.

The description doesn't make sense for Rc as you can't put an owned pointer in an Rc so the doc becomes confusing. If there were an indication that the doc was inherited it would be better.

  • impl Clone for Rc
    • fn clone(&self) -> Rc doc inherited from trait Clone
      • Returns a copy of the value. The contents of owned pointers are copied to maintain uniqueness, while the contents of managed pointers are not copied.
@huonw
Copy link
Member

huonw commented Feb 2, 2014

I personally think we should just follow haskell's lead and omit the docs from traits (I'm happy to differ from haddock and keep the individual method signatures displayed still, and to show any explicit docs on the impl'd methods).

The docs from the trait are not specific to the current leading to confusion (depending on the wording, as this issue shows), and are, in many cases, just useless filler (why does one need to navigate around the same doc comment for Clone::clone on nearly every type definition page?).

The trait definition are clickable, so a user can easily navigate to the trait to see the docs there, if necessary.

@flaper87
Copy link
Contributor

flaper87 commented Feb 2, 2014

I agree with @huonw here. This also implicitly encourages developers to document the different implementations of Traits

flip1995 pushed a commit to flip1995/rust that referenced this issue Dec 28, 2023
stop [`bool_comparison`]'s suggestion from consuming parentheses

fixes: rust-lang#9907

---

changelog: stop [`bool_comparison`]'s suggestion from consuming parentheses
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
E-easy Call for participation: Easy difficulty. Experience needed to fix: Not much. Good first issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

No branches or pull requests

3 participants