Skip to content

missing_doc_code_examples lint complains about foreign trait implementations #76450

Closed
@skreborn

Description

@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

Activity

added
requires-nightlyThis issue requires a nightly compiler in some way.
T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
on Sep 7, 2020
jyn514

jyn514 commented on Sep 7, 2020

@jyn514
Member
added
A-doc-coverageArea: Calculating how much of a crate has documentation
A-lintsArea: Lints (warnings about flaws in source code) such as unused_mut.
on Sep 7, 2020
GuillaumeGomez

GuillaumeGomez commented on Sep 10, 2020

@GuillaumeGomez
Member

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

jyn514

jyn514 commented on Sep 10, 2020

@jyn514
Member

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

GuillaumeGomez

GuillaumeGomez commented on Sep 10, 2020

@GuillaumeGomez
Member

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

jyn514 commented on Sep 10, 2020

@jyn514
Member

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

GuillaumeGomez

GuillaumeGomez commented on Sep 10, 2020

@GuillaumeGomez
Member

That's mainly my position yes. :)

skreborn

skreborn commented on Sep 10, 2020

@skreborn
Author

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

GuillaumeGomez commented on Sep 10, 2020

@GuillaumeGomez
Member

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

jyn514 commented on Sep 10, 2020

@jyn514
Member

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.

22 remaining items

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-doc-coverageArea: Calculating how much of a crate has documentationA-lintsArea: Lints (warnings about flaws in source code) such as unused_mut.C-bugCategory: This is a bug.E-needs-testCall for participation: An issue has been fixed and does not reproduce, but no test has been added.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.requires-nightlyThis issue requires a nightly compiler in some way.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Participants

      @skreborn@Manishearth@GuillaumeGomez@jyn514

      Issue actions

        `missing_doc_code_examples` lint complains about foreign trait implementations · Issue #76450 · rust-lang/rust