Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   Ani Sinha <ani@anisinha.ca>
To:     linux-kernel@vger.kernel.org
Cc:     anirban.sinha@nokia.com, mikelley@microsoft.com,
        Ani Sinha <ani@anisinha.ca>,
        Andy Whitcroft <apw@canonical.com>,
        Joe Perches <joe@perches.com>,
        Dwaipayan Ray <dwaipayanray1@gmail.com>,
        Lukas Bulwahn <lukas.bulwahn@gmail.com>
Subject: [PATCH v3] checkpatch: add a rule to check general block comment style
Date:   Wed, 14 Jul 2021 12:04:22 +0530
Message-Id: <20210714063422.2164699-1-ani@anisinha.ca>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

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
line #1: FILE: drivers/net/t.c:1:
+    /* foo */

WARNING: networking block comments don't use an empty /* line, use /* Comment...
line #4: FILE: drivers/net/t.c:4:
+    /*
+     * foo

WARNING: Block comments use a trailing */ on a separate line
line #11: FILE: drivers/net/t.c:11:
+     * bar */

total: 0 errors, 3 warnings, 0 checks, 11 lines checked


For a non-networking related code we see the following when run for
the same file:

$ ./scripts/checkpatch.pl -f arch/x86/kernel/t.c
WARNING: Missing or malformed SPDX-License-Identifier tag in line 1
line #1: FILE: arch/x86/kernel/t.c:1:
+    /* foo */

WARNING: Block comments use a leading /* on a separate line
line #7: FILE: arch/x86/kernel/t.c:7:
+    /* foo

WARNING: Block comments use a leading /* on a separate line
line #10: FILE: arch/x86/kernel/t.c:10:
+    /* foo

WARNING: Block comments use a trailing */ on a separate line
line #11: FILE: arch/x86/kernel/t.c:11:
+     * 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 <ani@anisinha.ca>
---
 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.
v3: line numbers got lost in the commit log as git eliminated all lines
    starting with '#'. Fixed it by prefixing with word 'line'. The work
    'line' does not however appear in the checkpatch.pl output.
 
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