2023-09-26 20:10:47

by Joe Perches

Subject: Re: [PATCH v2] checkpatch: warn about multi-line comments without an empty /* line

On Tue, 2023-09-26 at 21:24 +0200, Petr Tesarik wrote:
> According to Documentation/process/coding-style.rst, the preferred style
> for multi-line comments outside net/ and drivers/net/ 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.
> */
>
> Signed-off-by: Petr Tesarik <[email protected]>
[]
> diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
[]
> @@ -4006,6 +4006,14 @@ sub process {
> "networking block comments don't use an empty /* line, use /* Comment...\n" . $hereprev);
> }
>
> +# Non-networking without an initial /*
> + if ($realfile !~ m@^(drivers/net/|net/)@ &&
> + $prevrawline =~ /^\+[ \t]*\/\*.*[^ \t]$/ &&
> + $rawline =~ /^\+[ \t]*\*/) {
> + WARN("BLOCK_COMMENT_STYLE",
> + "multi-line block comments should start with an empty /* line\n" . $hereprev);
> + }
> +
> # Block comments use * on subsequent lines
> if ($prevline =~ /$;[ \t]*$/ && #ends in comment
> $prevrawline =~ /^\+.*?\/\*/ && #starting /*

Still nack. Too many existing instances.

$ git grep '/\*.*' -- '*.[ch]' | \
grep -v '/\*.*\*/' | \
grep -v -P "/\*\s*$" | \
grep -v '/\*\*' | \
grep -v "SPDX-License" | \
grep -v -P '^drivers/net|^net/' | \
wc -l
51834

2023-09-26 23:57:04

by Petr Tesařík

Subject: Re: [PATCH v2] checkpatch: warn about multi-line comments without an empty /* line

On Tue, 26 Sep 2023 12:56:33 -0700
Joe Perches <[email protected]> wrote:

> On Tue, 2023-09-26 at 21:24 +0200, Petr Tesarik wrote:
> > According to Documentation/process/coding-style.rst, the preferred style
> > for multi-line comments outside net/ and drivers/net/ 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.
> > */
> >
> > Signed-off-by: Petr Tesarik <[email protected]>
> []
> > diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> []
> > @@ -4006,6 +4006,14 @@ sub process {
> > "networking block comments don't use an empty /* line, use /* Comment...\n" . $hereprev);
> > }
> >
> > +# Non-networking without an initial /*
> > + if ($realfile !~ m@^(drivers/net/|net/)@ &&
> > + $prevrawline =~ /^\+[ \t]*\/\*.*[^ \t]$/ &&
> > + $rawline =~ /^\+[ \t]*\*/) {
> > + WARN("BLOCK_COMMENT_STYLE",
> > + "multi-line block comments should start with an empty /* line\n" . $hereprev);
> > + }
> > +
> > # Block comments use * on subsequent lines
> > if ($prevline =~ /$;[ \t]*$/ && #ends in comment
> > $prevrawline =~ /^\+.*?\/\*/ && #starting /*
>
> Still nack. Too many existing instances.
>
> $ git grep '/\*.*' -- '*.[ch]' | \
> grep -v '/\*.*\*/' | \
> grep -v -P "/\*\s*$" | \
> grep -v '/\*\*' | \
> grep -v "SPDX-License" | \
> grep -v -P '^drivers/net|^net/' | \
> wc -l
> 51834

Um. Not everything that is currently found in the source tree would be
accepted as new code by today's standards...

As it stands, the script checks the special case for net/ and
drivers/net/ but does not help prevent unnecessary respins, like this
one:

https://lore.kernel.org/linux-iommu/[email protected]/

OTOH if we don't want to warn about multi-line comments, maybe we don't
want to call it the preferred style, and the corresponding paragraph
should be removed from coding-style.rst. Do you suggest I try that
instead?

Petr T