linux-kernel - [RFC PATCH 10/10] rust: kbuild: enable `doc

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: <20250324210359.1199574-11-ojeda@kernel.org>
Date: Mon, 24 Mar 2025 22:03:57 +0100
From: Miguel Ojeda <ojeda@...nel.org>
To: Miguel Ojeda <ojeda@...nel.org>,
	Alex Gaynor <alex.gaynor@...il.com>
Cc: 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>,
	rust-for-linux@...r.kernel.org,
	linux-kernel@...r.kernel.org,
	patches@...ts.linux.dev,
	Masahiro Yamada <masahiroy@...nel.org>,
	Nathan Chancellor <nathan@...nel.org>,
	Nicolas Schier <nicolas@...sle.eu>,
	linux-kbuild@...r.kernel.org
Subject: [RFC PATCH 10/10] rust: kbuild: enable `doc_markdown` Clippy lint

Clippy supports the `doc_markdown` lint [1] since 2016 [2]:

    Checks for the presence of _, :: or camel-case words outside ticks
    in documentation.

It is a very common note in Linux kernel reviews to mention that
documentation is missing a Markdown code span, e.g.:

    /// Length of the data must be less than data_size.

should have been:

    /// Length of the data must be less than `data_size`.

This lint can identify some of those cases automatically for us.

It also caught for us other typos or mis-documentation, such as a missing
code block.

Thus enable it, now that the tree is sufficiently clean.

Relatedly, it would be nice to have something similar [3] even for
comments (not just documentation), as well as for possible intra-doc links
(which should also have less false positives).

Link: https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown [1]
Link: https://github.com/rust-lang/rust-clippy/commit/42bf37f49f49829507be4f2dfd6c5db9b8234b66 [2]
Link: https://github.com/rust-lang/rust/issues/131510 [3]
Link: https://lore.kernel.org/rust-for-linux/CANiq72=aVRMvOaU48DBLL=p+VoG3RvHK+K48XQhvHw3ARc0BNg@mail.gmail.com/
Signed-off-by: Miguel Ojeda <ojeda@...nel.org>
---
 .clippy.toml | 4 ++++
 Makefile     | 1 +
 2 files changed, 5 insertions(+)

diff --git a/.clippy.toml b/.clippy.toml
index 815c94732ed7..adc32c88176c 100644
--- a/.clippy.toml
+++ b/.clippy.toml
@@ -9,3 +9,7 @@ disallowed-macros = [
     # it here, see: https://github.com/rust-lang/rust-clippy/issues/11303.
     { path = "kernel::dbg", reason = "the `dbg!` macro is intended as a debugging tool" },
 ]
+
+doc-valid-idents = [
+    "KUnit",
+]
diff --git a/Makefile b/Makefile
index 70bdbf2218fc..5d6baedc097f 100644
--- a/Makefile
+++ b/Makefile
@@ -477,6 +477,7 @@ export rust_common_flags := --edition=2021 \
 			    -Wrust_2018_idioms \
 			    -Wunreachable_pub \
 			    -Wclippy::all \
+			    -Wclippy::doc_markdown \
 			    -Wclippy::ignored_unit_patterns \
 			    -Wclippy::mut_mut \
 			    -Wclippy::needless_bitwise_bool \
--
2.49.0