checkpatch.pl: Add warning for // comments on private Rust items
Subsystems (2)
v2 cover checkpatch.pl: Add warning for // comments on private Rust items
Hi,
Background
----------
The Rust-for-Linux project currently lacks enforcement of documentation for private Rust items, as highlighted in https://github.com/Rust-for-Linux/linux/issues/1157.
While rustc already lints missing documentation for public items, private items remain unchecked. This patch series aims to close that gap by ensuring proper documentation practices for private Rust items in the kernel.
The actual solution comes in several parts
------------------------------------------
1) Patch 1 : Implements detection logic to emit warnings for improperly documented private Rust items (e.g., // comments instead of ///).
2) Patch 2 : Adds an auto-fix mechanism via the --fix option to help developers correct documentation issues.
Results
--------------------
The following implementation has been tested against real patches:
- https://lore.kernel.org/rust-for-linux/[email protected]/T/#t
- https://lore.kernel.org/rust-for-linux/[email protected]/T/#t
- https://lore.kernel.org/rust-for-linux/[email protected]/T/#u
and this file:
// SPDX-License-Identifier: GPL-2.0
// Simple comment - should not trigger
// Returns a reference to the underlying [cpufreq::Table]. - should trigger #[inline]
fn table(&self) -> &cpufreq::Table {
// SAFETY: The `ptr` is guaranteed by the C code to be valid. - should not trigger
unsafe { cpufreq::Table::from_raw(self.ptr) }
}// Improper doc comment for a private function. - should trigger
fn test() -> u32 {
42
}/// Proper doc comment for a private function. - should not trigger
fn proper_doc() -> u32 {
42
}// TODO: implement more logic - should not trigger fn todo_marker() -> bool {
true
}
// Just a regular comment not followed by code - should not trigger
pub fn public_function() {
// Public function - should not trigger
}// Test - should trigger
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, PartialOrd)] struct Point2D {
pub x: f32,
pub y: f32
}
// Test - should not trigger
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, PartialOrd)] pub struct Point2D {
pub x: f32,
pub y: f32
}
// Test - should not trigger
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, PartialOrd)] pub struct Point2D {
pub x: f32,
pub y: f32
}
mod test_module {
// Module inner comment - should not trigger
}// Comment before macro - should trigger
macro_rules! my_macro {
// Comment inside macro - should not trigger
() => {};
}// Comment before public macro - should not trigger #[macro_export]macro_rules! my_public_macro {
}
// Comment before unsafe block - should not trigger
unsafe {
// Comment inside unsafe block - should not trigger
let x = 5;
}// Comment with unsafe word - should trigger
fn with_unsafe_keyword() {
println!("test");
}// Comment with code example: - should trigger
// let x = 5; - should trigger
fn with_code_example() {
println!("test");
}// NOTE: important consideration - should not trigger fn note_marker() -> bool {
true
}
// Comment with code example: - should not trigger /// let x = 5; - should not trigger
fn with_mixed_comments() {
println!("test");
}which led to this output:
WARNING: Consider using /// for private item documentation (line 5) #7: FILE: ./test.rs:7:
+// Returns a reference to the underlying [cpufreq::Table]. - should trigger
WARNING: Consider using /// for private item documentation (line 12) #13: FILE: ./test.rs:13:
+// Improper doc comment for a private function. - should trigger
WARNING: Consider using /// for private item documentation (line 33) #36: FILE: ./test.rs:36:
+// Test - should trigger
WARNING: Consider using /// for private item documentation (line 61) #62: FILE: ./test.rs:62:
+// Comment before macro - should trigger
WARNING: Consider using /// for private item documentation (line 80) #81: FILE: ./test.rs:81:
+// Comment with unsafe word - should trigger
WARNING: Consider using /// for private item documentation (line 85) #87: FILE: ./test.rs:87:
+// Comment with code example: - should trigger
WARNING: Consider using /// for private item documentation (line 86) #87: FILE: ./test.rs:87:
+// let x = 5; - should trigger
total: 0 errors, 7 warnings, 101 lines checked
NOTE: For some of the reported defects, checkpatch may be able to
mechanically convert to the typical style using --fix or --fix-inplace.
./test.rs has style problems, please review.
NOTE: If any of the errors are false positives, please report
them to the maintainer, see CHECKPATCH in MAINTAINERS.
To: Andy Whitcroft <[email protected]>
To: Joe Perches <[email protected]>
To: Dwaipayan Ray <[email protected]>
To: Lukas Bulwahn <[email protected]>
To: Miguel Ojeda <[email protected]>
To: Alex Gaynor <[email protected]>
To: Boqun Feng <[email protected]>
To: Gary Guo <[email protected]>
To: Björn Roy Baron <[email protected]>
To: Benno Lossin <[email protected]>
To: Andreas Hindborg <[email protected]>
To: Alice Ryhl <[email protected]>
To: Trevor Gross <[email protected]>
To: Danilo Krummrich <[email protected]>
To: Nathan Chancellor <[email protected]>
To: Nick Desaulniers <[email protected]>
To: Bill Wendling <[email protected]>
To: Justin Stitt <[email protected]>
---
Changes in v2:
- Tested against real patches
- Link to v1: https://lore.kernel.org/all/20250419-checkpatch-rust-private-item-comment-v1-0-0f8bc109bd5a@arnaud-lcm.com/
---
Signature · 1 line
2.43.0
PATCH v2 1/2 checkpatch.pl: warn about // comments on private Rust items
This patch adds a checkpatch.pl warning to detect //-style comments placed above private Rust items.
---
Changes in v2:
- Don't trigger a warning when the block of comments above a private rust item contains at least one doc comment.
- Trigger warning on private macros.
- Link to v1: https://lore.kernel.org/all/[email protected]/
--- scripts/checkpatch.pl | 56 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+)
scripts/checkpatch.pl +56 -0
@@ -1987,6 +1987,41 @@ sub ctx_locate_comment { chomp($current_comment); return($current_comment); } + +sub ctx_get_comment_behind_rust_private_item { + my ($linenr) = @_; + my $start_line = $linenr - 1; + my $idx = $start_line; + + # Skip if it's a public Rust item (starts with 'pub') + return unless $rawlines[$start_line] !~ /^\+?\s*pub(\s|\([^)]*\)\s)/; + + # Check if it's an empty line + return unless $rawlines[$start_line] !~ /^\s*\+?\s*$/; + + # Check if it's a comment + return unless $rawlines[$start_line] !~ /^\+?\s*\/\/\/?\/?.*$/; + + # Check if it is a private macro + if ($rawlines[$start_line] =~ /^\+?\s*macro_rules!\s+([a-zA-Z_][a-zA-Z0-9_]*|#?[a-zA-Z_][a-zA-Z0-9_]*)\s*(?:\{|$)/ && $idx > 0) { + return unless $rawlines[$idx -1] !~ /^\+?\s*#\s*\[\s*macro_export\s*\]\s*$/; + } else { + # Check if it's a Rust item + return unless $rawlines[$start_line] =~ /^\+?\s*\b(fn|struct|const|enum|trait|type|mod|impl|use)\b/; + } + + # Walk backwards through non-empty lines + $idx--; + while ($idx >= 0 && $rawlines[$idx] !~ /^\s*\+?\s*$/) { + # Check if is a document comment + return unless $rawlines[$idx] !~ m@^\+?\s*///([^/].*)?$@; + $idx--; + } + + return ($idx+1, $start_line); +} + + sub ctx_has_comment { my ($first_line, $end_line) = @_; my $cmt = ctx_locate_comment($first_line, $end_line);
@@ -2950,6 +2985,27 @@ sub process { } } +# check for incorrect use of `//` instead of `\\\` for doc comments in Rust + if ($perl_version_ok && $realfile =~ /\.rs$/) { + my ($start_l, $end_l) = ctx_get_comment_behind_rust_private_item($linenr); + if (defined($start_l) && defined($end_l)) { + for (my $i = $start_l; $i <= $end_l; $i++) { + my $comment_line = $rawlines[$i - 1]; + next unless $comment_line =~ m@^\+//([^/].*)$@; + my $comment = $1; + + # Skip obvious non-doc comments + next if $comment =~ m@^\s*(?:TODO|FIXME|XXX|NOTE|HACK|SAFETY):?@i; + next if $comment =~ m@^\s*[[:punct:]]{2,}@; + my $line_issue = $i - 3; + + WARN("POSSIBLE_MISSING_RUST_DOC", + "Consider using `///` for private item documentation (line $line_issue)\n" . + "$here\n$comment_line"); + } + } + } + # Check the patch for a From: if (decode("MIME-Header", $line) =~ /^From:\s*(.*)/) { $author = $1;
Signature · 1 line
2.43.0
Quoted 6 lines · Arnaud Lecomte
The Rust-for-Linux project currently lacks enforcement of documentation for private Rust items, as highlighted in https://github.com/Rust-for-Linux/linux/issues/1157.
While rustc already lints missing documentation for public items, private items remain unchecked. This patch series aims to close that gap by ensuring proper documentation practices for private Rust items in the kernel.
To clarify, it is not that we want to enforce all private items to have documentation, but rather to catch the odd // comment that was supposed to be documentation. (The background here seems to imply the former.)
Quoted 2 lines
// Improper doc comment for a private function. - should trigger fn
test()-> u32 {
Since this is just a checkpatch.pl warning, it may be fine to always warn, i.e. the submitter can always decide if it is a false positive or not -- I hope it does not become too annoying :)
(That is why the issue mentioned perhaps using some heuristics to decide).
Quoted 1 line
WARNING: Consider using
///for private item documentation (line 33)
This text seems fine to me, although I wonder if newcomers to Rust may just transform it into /// when seeing this warning, i.e. the opposite mistake. Perhaps we can make it more "conditional" (even if the "Consider" is already there), e.g.
Consider using /// if this comment was intended as documentation
Quoted 5 lines
To: Nathan Chancellor <[email protected]>
To: Nick Desaulniers <[email protected]>
To: Bill Wendling <[email protected]>
To: Justin Stitt <[email protected]>
Cc: [email protected]
Should the LLVM subsystem be Cc'd?
Thanks for the patches!
Cheers,
Miguel