Repository: rust
Issue: Allow empty override of a provided trait method for documentation purposes
Labels: T-rustdoc,A-trait-system,T-core,C-feature-request

I believe it should be possible for an implementation to override a provided trait method without providing a body, for the sole purpose of overriding its documentation in a forwards-compatible, maintenance-free manner.

Given the following trait which has one required method and one automatically provided method:

```rust
trait Awaitable {
    /// The type returned by [`wait()`] and co. in case of success.
    type T;
    /// The type returned by [`wait()`] and co. in case of failure.
    type Error;

    /// Does a generic wait on thingy and returns the status of the wait as a result.
    fn wait(&self) -> Result<Self::T, Self::Error>;

    /// Does a generic wait on thingy and returns the status of the wait as a boolean.
    ///
    /// Can be overridden by implementations that have an optimized alternative to internally calling `wait()`.
    fn try_wait(&self) -> bool {
        match self.wait() {
            Ok(_) => true,
            Err(_) => false,
        }
    }
}
```

An implementation currently can provide its own version of `Awaitable::wait()` and override the documentation _of that one method_ to be specific to its implementation:

```rust
struct Foo {}

impl Awaitable for Foo {
    type T = ();
    type Error = core::convert::Infallible;

    /// Waits for the `Foo` widget to become available and then attempts to bamboozle the
    /// phalange, reporting the outcome of the operation.
    fn wait(&self) -> Result<Self::T, Self::Error>;
}
```

It is opting into the default behavior of `try_wait()` because it does not want/need to override the impl, but this means that while the rustdoc page for `Foo` contains the customized documentation for `wait()` that is specific to this implementation, on that same page the documentation for `try_wait()` will default to the generic text from the original `Awaitable` trait. In order to customize the text for `try_wait()` as well, the developer must copy-and-paste the default provided implementation from `awaitable.rs` to `foo.rs` and then provide their own documentation.

I am proposing that it should be possible to provide a "stub" implementation for already-provided trait methods that continues to inherit the implementation from the trait definition, but allows the developer to override its documentation, like so:

```rust
struct Foo {}

impl Awaitable for Foo {
    type T = ();
    type Error = core::convert::Infallible;

    /// Waits for the `Foo` widget to become available and then attempts to bamboozle the
    /// phalange, reporting the outcome of the operation including the specific error in
    /// case of failure.
    fn wait(&self) -> Result<(), Infallible>;

    /// Waits for the `Foo` widget to become available and then attempts to bamboozle the
    /// phalange, reporting only the success/failure status of the outcome.
    fn try_wait(&self) -> bool;
}
```

Unlike with copying-and-pasting the *current* default implementation of `try_wait` from `awaitable.rs`, with this approach the developer would be "tracking" the upstream behavior. If the default implementation changes - perhaps to fix a bug or improve performance - the implementation of `Foo::try_wait()` would change accordingly, just like it would if the method were not overridden at all.

Additionally, the docs for the provided method should reflect the types as typed-out in the stub - just like `Foo::wait()` will be shown with a return type of `Result<(), Infallible>` instead of `Result<Self::T, Self::Error>`, it should be possible to override the types displayed on the docs page for the "partially overridden" or "declaration-only override" of the provided method `Foo::try_wait()` as well.

@rustbot label -C-bug +C-feature-request +T-rustdoc +T-core +A-traits