rustdoc: Trait methods with default implementations are never hidden

[phil-opp]

Background

Rustdoc currently hides implementated trait methods behind a "Show hidden undocumented items" switch, unless a new doc comment was supplied on the method implementation. For example, consider this code:

pub trait Test {
    /// This trait method does X...
    fn foo(&self);

    /// This trait method does Y...
    fn bar(&self);
}

pub struct TestImpl;

impl Test for TestImpl {
    fn foo(&self) {}

    /// A special trait implementation that deserves
    /// some custom documentation.
    fn bar(&self) {}
}

The generated documentation looks like this:

Only the bar method is shown because its implementation has a custom doc comment, which indicates that it is somewhat important or special.

Methods with Default Implementations

Trait methods can have default implementations directly in the trait definition:

pub trait Foo {
    /// Do something
    fn do_something(&self);

    /// Do something twice
    fn do_something_twice(&self) {
        self.do_something(); self.do_something();
    }
}

pub struct Bar;

impl Foo for Bar {
    fn do_something(&self) {
        println!("Bar");
    }
}

Since do_something_twice has a default implementation, we don't need to provide an implementation when implementing the trait.

The generated documentation looks like this:

The do_something_twice method is shown even though it is not mentioned in the impl block. I think the reason is that there is a doc comment on the used default implementation in the trait definition, which rustdoc treats exactly like the doc comment on the bar implementation above.

The Problem

The current behavior causes confusion in several ways:

• Default methods and method implementations with a custom doc string look exactly the same:
  
  Here, only the do_something implementation provides an own doc comment. The do_something_twice method looks exactly the same, but it is just a default implementation with the doc comment from the trait definition.
• Often, the unimportant methods with default implementations are shown, while more important ones are hidden. For example, this CommandExt implementation shows only the deprecated before_exec function because it has a default implementation.
• It sometimes shows a seemingly random set of methods, leading to confusion. For example, for most implementations of PartialEq only the ne method is shown. The reason is that it has a default implementation around eq, but this doesn't really matter to the reader.

A Possible Solution

I think it would be more intuitive to also hide methods with default implementations when they're not overridden in the impl block.

Meta

This issue was originally reported in #56546 (comment). I used some examples from this thread for creating this issue.

cc @GuillaumeGomez

[GuillaumeGomez]

I'll make the PR to change this behavior and then we'll see what others think about it.