Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::3:1 as permitted sender) client-ip=2620:137:e000::3:1;
Date:   Tue, 26 Sep 2023 22:16:00 +0200
From:   Petr =?UTF-8?B?VGVzYcWZw61r?= <petr@tesarici.cz>
To:     Joe Perches <joe@perches.com>
Cc:     Andy Whitcroft <apw@canonical.com>,
        Dwaipayan Ray <dwaipayanray1@gmail.com>,
        Lukas Bulwahn <lukas.bulwahn@gmail.com>,
        open list <linux-kernel@vger.kernel.org>,
        Catalin Marinas <catalin.marinas@arm.com>
Subject: Re: [PATCH v2] checkpatch: warn about multi-line comments without
 an empty /* line
Message-ID: <20230926221521.08f4a64d@meshulam.tesarici.cz>
In-Reply-To: <1adcfeaa4bd01d59a349daa697cc007e81bc81b1.camel@perches.com>
References: <20230926192400.19366-1-petr@tesarici.cz>
        <1adcfeaa4bd01d59a349daa697cc007e81bc81b1.camel@perches.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk

On Tue, 26 Sep 2023 12:56:33 -0700
Joe Perches <joe@perches.com> 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 <petr@tesarici.cz>  
> []
> > 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/ZRMgObTMkfq8Bjbe@arm.com/

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