linux-kernel - [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: <20250216213827.3752586-2-benno.lossin@proton.me>
Date: Sun, 16 Feb 2025 21:38:42 +0000
From: Benno Lossin <benno.lossin@...ton.me>
To: 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>, Benno Lossin <benno.lossin@...ton.me>, Andreas Hindborg <a.hindborg@...nel.org>, Alice Ryhl <aliceryhl@...gle.com>, Trevor Gross <tmgross@...ch.edu>, Danilo Krummrich <dakr@...nel.org>
Cc: linux-kbuild@...r.kernel.org, linux-kernel@...r.kernel.org, rust-for-linux@...r.kernel.org
Subject: [PATCH 2/2] rust: enable `too-long-first-doc-paragraph` clippy lint

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
 
-- 
2.47.2