Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rustdoc shouldn't lint about missing code examples in trait impls #88741

Closed
hnj2 opened this issue Sep 8, 2021 · 0 comments · Fixed by #88745
Closed

Rustdoc shouldn't lint about missing code examples in trait impls #88741

hnj2 opened this issue Sep 8, 2021 · 0 comments · Fixed by #88745

Comments

@hnj2
Copy link
Contributor

hnj2 commented Sep 8, 2021

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;
/// ```
pub struct SomeStruct;

impl Clone for SomeStruct {
    fn clone(&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

  1. This is inconsistent with the missing_docs lint, which does not require documentation for Trait implementations.
  2. The documentation errors/warnings should be issued when compiling the Traits documentation (as is the case with e.g. the missing documentation lint).
  3. Once "Rustdoc shouldn't lint about missing code examples in derived traits #81775" is fixed, the missing code examples lint is inconsistent with its own behavior when using derive macro.

Workarounds

There are two options available to avoid these documentation errors:

  1. 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:
    1. It cause a lot of copy-paste code duplication.
    2. In most cases the traits documentation is preferred to an implementors documentation.
    3. 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.
    4. 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.
    5. 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.
  2. One can allow missing doc code examples for each of these cases:
    #[allow(rustdoc::missing_doc_code_examples)]
    impl Clone for SomeStruct {
        fn clone(&self) -> Self { Self }
    }
    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.

GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this issue Sep 9, 2021
… 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#88741

fixes rust-lang#88741

r? `@jyn514`
Manishearth added a commit to Manishearth/rust that referenced this issue Sep 12, 2021
… 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#88741

fixes rust-lang#88741

r? ``@jyn514``
workingjubilee added a commit to workingjubilee/rustc that referenced this issue Sep 12, 2021
… 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#88741

fixes rust-lang#88741

r? ```@jyn514```
@bors bors closed this as completed in 1cd17ad Sep 13, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant