linux-kernel - CodingStyle vs checkpatch for block comments

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Date:	Tue, 3 Apr 2012 13:25:52 -0400
From:	Chris Metcalf <cmetcalf@...era.com>
To:	Joe Perches <joe@...ches.com>
CC:	Kautuk Consul <consul.kautuk@...il.com>,
	"David S. Miller" <davem@...emloft.net>,
	Linux Kernel Mailing List <linux-kernel@...r.kernel.org>
Subject: CodingStyle vs checkpatch for block comments

(Adding linux-kernel to the cc's and restating the question...)

I accepted a patch from Kautuk Consul and adjusted his comment style, but
he pointed out that he had changed his comment style based on a warning
from checkpatch.

The Documentation/CodingStyle file says:

    The preferred style for long (multi-line) comments is:

       /*
        * 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.
        */

However, a new change to "checkpatch --strict" by Joe Perches, commit
aad4f61498, causes this construct to be flagged as a warning if (and only
if) it is preceded by a blank line.  Joe said the change was to support
David Miller's preferred style, but that he didn't much care one way or
another.

The relevant code in checkpatch.pl is:

                if ($rawline =~ /^\+[ \t]*\/\*[ \t]*$/ &&
                    $prevrawline =~ /^\+[ \t]*$/) {
                        CHK("BLOCK_COMMENT_STYLE",
                            "Don't begin block comments with only a /*
line, use /* comment...\n" . $hereprev);
                }

So, my questions -

1. I'm not sure what the regexps are really trying to avoid.  Presumably a
blank line followed by a block comment is OK?  Certainly the kernel sources
are full of this construct.

2. The actual warning message emitted seems to directly contradict the
CodingStyle document, so presumably we should either clarify the message,
or update CodingStyle if we're really trying to change the style.

-- 
Chris Metcalf, Tilera Corp.
http://www.tilera.com

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/