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 a non-networking related code we see the following when run against
the same file:
$ ./scripts/checkpatch.pl -f arch/x86/kernel/t.c
WARNING: Missing or malformed SPDX-License-Identifier tag in line 1
+ /* foo */
WARNING: Block comments use a leading /* on a separate line
+ /* foo
WARNING: Block comments use a leading /* on a separate line
+ /* foo
WARNING: Block comments use a trailing */ on a separate line
+ * bar */
total: 0 errors, 4 warnings, 11 lines checked
In the second case, there is no warning on line 4 and in the first
case, there is no warning on line 10.
Signed-off-by: Ani Sinha <[email protected]>
---
scripts/checkpatch.pl | 8 ++++++++
1 file changed, 8 insertions(+)
Changelog:
v1: initial patch
v2: commit log updated to reflect the output from checkpatch.pl
when run against the same file both in networking and
non-networking case. This helps in comparing results apples to
apples.
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