CodingStyle vs checkpatch for block comments

[Chris Metcalf]

(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@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/