Closed
Description
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
Metadata
Metadata
Assignees
Labels
Area: Calculating how much of a crate has documentationArea: Lints (warnings about flaws in source code) such as unused_mut.Category: This is a bug.Call for participation: An issue has been fixed and does not reproduce, but no test has been added.Relevant to the rustdoc team, which will review and decide on the PR/issue.This issue requires a nightly compiler in some way.
Activity
jyn514 commentedon Sep 7, 2020
cc @GuillaumeGomez
GuillaumeGomez commentedon Sep 10, 2020
I think the current lint behavior is correct. The issue here is on the core lib side. I opened #76568 to fix it.
jyn514 commentedon Sep 10, 2020
Maybe the lint shouldn't warn when implementing a foreign trait? By the same rationale as #56922.
GuillaumeGomez commentedon Sep 10, 2020
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 commentedon Sep 10, 2020
I guess if you can add docs on the implementation it makes sense - you have a way to fix it.
GuillaumeGomez commentedon Sep 10, 2020
That's mainly my position yes. :)
skreborn commentedon Sep 10, 2020
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 commentedon Sep 10, 2020
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 commentedon Sep 10, 2020
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