The preferred style for long (multi-line) comments is:
.. code-block:: c
/*
* This is the preferred style for multi-line
* comments in the Linux kernel source code.
* Please use it consistently.
*
* Description: A column of asterisks on the left side,
* with beginning and ending almost-blank lines.
*/
It seems rule in checkpatch.pl is missing to ensure this for
non-networking related changes. This patch adds this rule.
Tested with
$ cat drivers/net/t.c
/* foo */
/*
* foo
*/
/* foo
*/
/* foo
* bar */
$ ./scripts/checkpatch.pl -f drivers/net/t.c
WARNING: Missing or malformed SPDX-License-Identifier tag in line 1
+ /* foo */
WARNING: networking block comments don't use an empty /* line, use /* Comment...
+ /*
+ * foo
WARNING: Block comments use a trailing */ on a separate line
+ * bar */
total: 0 errors, 3 warnings, 0 checks, 11 lines checked
For one of my own patches where block comment did not start with an empty
line,
$ ./scripts/checkpatch.pl 0001-my.patch
WARNING: Block comments use a leading /* on a separate line
+ /* TSC should be marked as unstable only after Hyper-V
total: 0 errors, 1 warnings, 20 lines checked
The patch is question is posted here: https://lkml.org/lkml/2021/7/12/3527
Signed-off-by: Ani Sinha <[email protected]>
---
scripts/checkpatch.pl | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index 23697a6b1eaa..5f047b762aa1 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -3833,6 +3833,14 @@ sub process {
"networking block comments don't use an empty /* line, use /* Comment...\n" . $hereprev);
}
+# Block comments use /* on a line of its own
+ if (!($realfile =~ m@^(drivers/net/|net/)@) &&
+ $rawline !~ m@^\+.*/\*.*\*/[ \t)}]*$@ && #inline /*...*/
+ $rawline =~ m@^\+.*/\*\*?+[ \t]*[^ \t]@) { # /* or /** non-blank
+ WARN("BLOCK_COMMENT_STYLE",
+ "Block comments use a leading /* on a separate line\n" . $herecurr);
+ }
+
# Block comments use * on subsequent lines
if ($prevline =~ /$;[ \t]*$/ && #ends in comment
$prevrawline =~ /^\+.*?\/\*/ && #starting /*
--
2.25.1