Skip to content

checkpatch.pl: Add warning for // comments on private Rust items

Arnaud Lecomte lkml llvm rust-for-linux 4 versions – In review

Get series with b4
b4 am [email protected] change-id 20250419-checkpatch-rust-private-item-comment-bb3a5281e5da

Versions newest first

  1. v3 Latest2 patches 7 repliesIn review inferred link
  2. v21 of 2 patches 1 replySuperseded inferred link
  3. v1 posting 2/22 patches 1 replySuperseded
Earlier versions · 1
VersionPostedPatchesRepliesStatus
v1 posting 1/20 of 2 patches0 repliesSuperseded

Patches in v3 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/2checkpatch.pl: warn about // comments on private Rust itemsscripts/checkpatch.pl+110 -05 replies
2/2checkpatch.pl: --fix support for `//` comments rust private itemsscripts/checkpatch.pl+4 -20 replies

Reviews trailers per patch

No Reviewed-by, Acked-by or Tested-by trailers for v3 yet.

Read the v3 thread

Cover letter [PATCH v3 0/2] 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 ///) through a set of heuristics.
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

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) }
}

// Meaning of life - should not trigger

fn test() -> u32 {
    42
}

/// Proper doc comment for a private function.

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 not trigger
struct Point2D {
pub x: f32,
pub y: f32
}

// Test - should not trigger
pub struct Point2D {
pub x: f32,
pub y: f32
}

mod test_module {
    // Module inner comment - should not trigger
}

// Comment before macro - should not trigger

macro_rules! my_macro {
    // Comment inside macro - should not trigger
    () => {};
}

// Comment before public macro - should not trigger 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 multiple
// Line
// Youhouuu
// - should trigger

fn with_unsafe_keyword() {
    println!("test");
}

// NOTE: important consideration - should not trigger fn note_marker() -> bool {
true
}

// Comment with code example: - should trigger
// ``` let x = 5; ```

fn with_mixed_comments() {
    println!("test");
}

which led to this output:
WARNING: Consider using /// if the comment was intended as documentation (line 5). +// Returns a reference to the underlying [cpufreq::Table]. - should trigger
WARNING: Consider using /// if the comment was intended as documentation (line 72). +// Comment with multiple
WARNING: Consider using /// if the comment was intended as documentation (line 73). +// Line
WARNING: Consider using /// if the comment was intended as documentation (line 74). +// Youhouuu
WARNING: Consider using /// if the comment was intended as documentation (line 75). +// - should trigger
WARNING: Consider using /// if the comment was intended as documentation (line 92). +// Comment with code example: - should trigger
total: 0 errors, 6 warnings, 96 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]>

Signature · 1 line
2.43.0