Re: [Qemu-devel] [PATCH] scripts/checkpatch.pl: Enforce multiline comment syntax

[Markus Armbruster]

Paolo Bonzini <address@hidden> writes:

> On 10/08/2018 11:41, Markus Armbruster wrote:
>>> Lone "/*" or "/**": 9986 cases
>>>     of which in the first column: 7617
>>>     of which the first line in the file (license headers): 2834
>>>     regex: ^[ \t]*/\*\*?[ \t]*$
>>>
>>> "/*" with the first line of the comment: 11246
>>>     of which in the first column: 4985
>>>     of which the first line in the file: 97
>>>     regex: ^[ \t]*/\*\*?+(?:(?!\*/).)+?$
>>>
>>> License headers almost always have the "lone /*" format.  Apart from
>>> license headers, 63% of the comments have the now-deprecated format.
>>>
>>> Inside functions, 73% of the comments have the now-deprecated format.
>>> Outside functions it's 50-50.  That's because there are 2024 doc
>>> comments, which in turn are 50% of the comments that are 1) outside the
>>> functions 2) using a lone "/*".
>>>
>>> So my proposal, which is actually consistent with what QEMU is doing, is
>>> the following:
>>>
>>> 1) the first line of a file should always be "/*", otherwise warn
>>>
>>> 2) a comment that starts with "/**" should have it on a lone line
>>>
>>> 3) every other multiline comment should start with
>>> "/*<whitespace><something>"
>> (3) is not consistent with what QEMU is doing in this case, since
>> according to your data there is no consistency in what QEMU is doing.
>
> 65-35, and 75-25 inside functions (comments outside should be doc
> comments so that's again a different story) is pretty consistent
> actually.  So no patch would be better in your opinion?

I'm fine with Peter's patch as is.  I'd also be fine with a tree-wide
conversion of comments to the preferred style on top.

I'd prefer not to reopen the debate.

If we reopen it, and reach a different consensus, we need a patch
enforcing it.

If we reopen it, and fail to reach consensus, there's nothing for a
patch to enforce.

Note that "always wing both ends, and star every line in between" and
"wing only the end, not the start, unless file's first line or /** doc
comment, and star every line in between" are not the only options.  A
weaker style rule would be "may wing the start, must wing the end, must
star every line in between".

That said, I reiterate my preference not to reopen the debate :)