You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
My suggestion is to exclude Trait implementations from the items that need to have doc code examples when using the rustdoc::missing_doc_code_examples lint.
Examples
Consider the following example:
//! docs//! ```//! let s = SomeStruct;//! ```#![deny(rustdoc::missing_doc_code_examples)]/// docs/// ```/// let s = SomeStruct;/// ```pubstructSomeStruct;implCloneforSomeStruct{fnclone(&self) -> Self{Self}}
The missing_doc_code_exmaples lint causes the following errors:
error: missing code example in this documentation
--> src/lib.rs:14:1
|
14 | / impl Clone for SomeStruct {
15 | | fn clone(&self) -> Self { Self }
16 | | }
| |_^
|
note: the lint level is defined here
--> src/lib.rs:6:9
|
6 | #![deny(rustdoc::missing_doc_code_examples)]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
error: missing code example in this documentation
--> src/lib.rs:15:5
|
15 | fn clone(&self) -> Self { Self }
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pros
This is inconsistent with the missing_docs lint, which does not require documentation for Trait implementations.
The documentation errors/warnings should be issued when compiling the Traits documentation (as is the case with e.g. the missing documentation lint).
There are two options available to avoid these documentation errors:
One can replace the traits documentations:
/// docs
/// ```
/// let c = SomeStruct.clone();
/// ```
impl Clone for SomeStruct {
/// docs
/// ```
/// let c = SomeStruct.clone();
/// ```
fn clone(&self) -> Self { Self }
}
This is a bad workaround because:
It cause a lot of copy-paste code duplication.
In most cases the traits documentation is preferred to an implementors documentation.
The Trait and it's associated methods, types, etc. can already have a documentation with code examples.
Those are not considered by the lint, which prompts the implementor rewrite the documentation or ignore the lint.
The Trait's provided methods might not have code examples (as is the case with Clone::clone_from).
Those is not considered by the lint.
The lint is inconsistent when it comes to required and provided methods of a trait (compare the previous two points).
Even though both types of methods are displayed equally in the documentation the missing doc code examples lint treats them differently.
One can allow missing doc code examples for each of these cases:
This workaround is also not ideal due to the amount of copy paste code duplication necessary, its inconsistency with derive macros and its inconsistency with other lints like the missing documentations lint.
Cons
The only good case (that I can think of) for the current behavior of the lint is:
If an implementation has some special behavior (like not implementing a method of a Trait) then the author of the implementation is reminded to document this behavior by the lint.
The text was updated successfully, but these errors were encountered:
… r=GuillaumeGomez
Allow missing code examples in trait impls.
Excludes Trait implementations from the items that need to have doc code examples when using the `rustdoc::missing_doc_code_examples` lint.
For details see rust-lang#88741fixesrust-lang#88741
r? `@jyn514`
… r=GuillaumeGomez
Allow missing code examples in trait impls.
Excludes Trait implementations from the items that need to have doc code examples when using the `rustdoc::missing_doc_code_examples` lint.
For details see rust-lang#88741fixesrust-lang#88741
r? ``@jyn514``
… r=GuillaumeGomez
Allow missing code examples in trait impls.
Excludes Trait implementations from the items that need to have doc code examples when using the `rustdoc::missing_doc_code_examples` lint.
For details see rust-lang#88741fixesrust-lang#88741
r? ```@jyn514```
My suggestion is to exclude Trait implementations from the items that need to have doc code examples when using the
rustdoc::missing_doc_code_examples
lint.Examples
Consider the following example:
The
missing_doc_code_exmaples
lint causes the following errors:Pros
missing_docs
lint, which does not require documentation for Trait implementations.Workarounds
There are two options available to avoid these documentation errors:
Those are not considered by the lint, which prompts the implementor rewrite the documentation or ignore the lint.
Clone::clone_from
).Those is not considered by the lint.
Even though both types of methods are displayed equally in the documentation the missing doc code examples lint treats them differently.
Cons
The only good case (that I can think of) for the current behavior of the lint is:
If an implementation has some special behavior (like not implementing a method of a Trait) then the author of the implementation is reminded to document this behavior by the lint.
The text was updated successfully, but these errors were encountered: