linux-kernel - Re: [PATCH 2/2] rust: enable `too-long-first-doc-paragraph` clippy lint

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <m2jz9p7ecj.fsf@posteo.net>
Date: Sun, 16 Feb 2025 21:46:04 +0000
From: Charalampos Mitrodimas <charmitro@...teo.net>
To: Benno Lossin <benno.lossin@...ton.me>
Cc: Masahiro Yamada <masahiroy@...nel.org>,  Nathan Chancellor
 <nathan@...nel.org>,  Nicolas Schier <nicolas@...sle.eu>,  Miguel Ojeda
 <ojeda@...nel.org>,  Alex Gaynor <alex.gaynor@...il.com>,  Boqun Feng
 <boqun.feng@...il.com>,  Gary Guo <gary@...yguo.net>,  Björn Roy Baron
 <bjorn3_gh@...tonmail.com>,  Andreas Hindborg <a.hindborg@...nel.org>,
  Alice Ryhl <aliceryhl@...gle.com>,  Trevor Gross <tmgross@...ch.edu>,
  Danilo Krummrich <dakr@...nel.org>,  linux-kbuild@...r.kernel.org,
  linux-kernel@...r.kernel.org,  rust-for-linux@...r.kernel.org
Subject: Re: [PATCH 2/2] rust: enable `too-long-first-doc-paragraph` clippy
 lint

Benno Lossin <benno.lossin@...ton.me> writes:

> Introduced in Rust 1.82.0 [1], this lint ensures that the first line of
> documentation is short. That is because those lines get rendered in the
> html version of the docs directly next to the items and should therefore
> be short.
> Additionally, a short first sentence might help developers remember the
> rest of the documentation if they have read it already before.
>
> Reviewers have pointed this out manually on several occasions, thus
> enable the lint.
>
> Here is an example error fixed in the previous commit:
>
>     error: first doc comment paragraph is too long
>       --> rust/kernel/driver.rs:13:1
>        |
>     13 | / /// The [`RegistrationOps`] trait serves as generic interface for subsystems (e.g., PCI, Platform,
>     14 | | /// Amba, etc.) to provide the corresponding subsystem specific implementation to register /
>     15 | | /// unregister a driver of the particular type (`RegType`).
>     16 | | ///
>     17 | | /// For instance, the PCI subsystem would set `RegType` to `bindings::pci_driver` and call
>        | |_^
>        |
>        = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#too_long_first_doc_paragraph
>        = note: `-D clippy::too-long-first-doc-paragraph` implied by `-D warnings`
>        = help: to override `-D warnings` add `#[allow(clippy::too_long_first_doc_paragraph)]`
>
>     error: aborting due to 1 previous error
>
> The exact length can be configured in the .clippy.toml if we need to do
> so.
>
> Link: https://github.com/rust-lang/rust-clippy/issues/12989 [1]
> Signed-off-by: Benno Lossin <benno.lossin@...ton.me>
> ---
>  Makefile | 1 +
>  1 file changed, 1 insertion(+)
>
> diff --git a/Makefile b/Makefile
> index 9e0d63d9d94b..d00cbeb63714 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -486,6 +486,7 @@ export rust_common_flags := --edition=2021 \
>  			    -Wclippy::undocumented_unsafe_blocks \
>  			    -Wclippy::unnecessary_safety_comment \
>  			    -Wclippy::unnecessary_safety_doc \
> +			    -Wclippy::too-long-first-doc-paragraph \
>  			    -Wrustdoc::missing_crate_level_docs \
>  			    -Wrustdoc::unescaped_backticks

Reviewed-by: Charalampos Mitrodimas <charmitro@...teo.net>