`missing_doc_code_examples` lint complains about foreign trait implementations

[skreborn]

The missing_doc_code_examples lint seems to be erroneously complaining about missing documentation examples where local types implement foreign traits (both from 3rd party crates and the standard library).

The example below should pass all checks as far as I can tell:

/// Foo.
pub struct Foo {
  /// Bar.
  pub bar: i32,
  /// Baz.
  pub baz: i32,
}

impl Neg for Foo {
  type Output = Self;

  #[inline]
  fn neg(self) -> Self::Output {
    Self::Output {
      bar: -self.bar,
      baz: -self.baz,
    }
  }
}

However, running cargo doc results in the following warnings:

warning: missing code example in this documentation
   --> foo.rs:9:1
    |
    | / impl Neg for Foo {
    | |   type Output = Self;
    | |
    | |   #[inline]
...   |
    | |   }
    | | }
    | |_^

warning: missing code example in this documentation
   --> foo.rs:13:3
    |
    | /   fn neg(self) -> Self::Output {
    | |     Self::Output {
    | |       bar: -self.bar,
    | |       baz: -self.baz,
    | |     }
    | |   }
    | |___^

Meta

rustc --version --verbose:

rustc 1.48.0-nightly (73dc675b9 2020-09-06)
binary: rustc
commit-hash: 73dc675b9437c2a51a975a9f58cc66f05463c351
commit-date: 2020-09-06
host: x86_64-pc-windows-msvc
release: 1.48.0-nightly
LLVM version: 11.0

[jyn514]

cc @GuillaumeGomez

[GuillaumeGomez]

I think the current lint behavior is correct. The issue here is on the core lib side. I opened #76568 to fix it.

[jyn514]

Maybe the lint shouldn't warn when implementing a foreign trait? By the same rationale as #56922.

[GuillaumeGomez]

Hmmm... I have shared feelings here: if a trait doesn't provided documentation "by default", doesn't it make sense to complain about it on the implementors?

[jyn514]

I guess if you can add docs on the implementation it makes sense - you have a way to fix it.

[GuillaumeGomez]

That's mainly my position yes. :)

[skreborn]

I guess if you can add docs on the implementation it makes sense - you have a way to fix it.

Unfortunately, that drags with itself more issues. First of all, I have to implement said examples on all of the implementations I write. Second, I have to copy (and correctly maintain said copy) the original example-less documentation onto every instance so that it's not lost by the language server and/or rustdoc.

While this isn't entirely impossible, it's a huge chore, especially when you implement multiple traits on tens of types at a time. While std could get its issues fixed, that hardly helps us with the rest of the crate ecosystem. As of now, I have about 300 warnings, and actually useful information just drowns in that flood.

[GuillaumeGomez]

You can disable the lint on a specific implementation in the worst case. However, the goal is to enforce more documentation through the ecosystem. If users start to complain about it to the crates' maintainers, I'm pretty sure the situation will improve pretty quickly.

[jyn514]

However, the goal is to enforce more documentation through the ecosystem. If users start to complain about it to the crates' maintainers, I'm pretty sure the situation will improve pretty quickly

I don't really like this approach - it should be fixable by you, not by bugging upstream maintainers. @Manishearth was saying something like that for #74563 I think.