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  PHC 
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date:   Tue, 27 Sep 2022 11:53:38 +0900
From:   Akira Yokosawa <>
To:     Kees Cook <>,
        Matthew Wilcox <>
Cc:     Jonathan Corbet <>,,,
Subject: Re: [PATCH] overflow: Fix kern-doc markup for functions


Somehow Kees added me in Cc:, so let me comment.  :-)

On Mon, 26 Sep 2022 14:09:10 -0700, Kees Cook wrote:
> On Mon, Sep 26, 2022 at 10:06:19PM +0100, Matthew Wilcox wrote:
>> On Mon, Sep 26, 2022 at 12:47:13PM -0700, Kees Cook wrote:
>>> -/** check_add_overflow() - Calculate addition with overflow checking
>>> +/**
>>> + * check_add_overflow - Calculate addition with overflow checking
>>>   *
>>>   * @a: first addend
>>>   * @b: second addend
>> Why did you remove the ()?  And why didn't you delete the blank line?
>> According to our documentation, the canonical form is:
>>   /**
>>    * function_name() - Brief description of function.
>>    * @arg1: Describe the first argument.
>>    * @arg2: Describe the second argument.
>>    *        One can provide multiple line descriptions
>>    *        for arguments.

Matthew, you call it the "canonical form", my take is more of a "template
that is known to work".

>> I don't usually complain about people getting that wrong, but when
>> people correct it to be wrong ...

I'd say "wrong" if "./scripts/kernel-doc -v -none include/linux/overflow.h"
complained or the resulting reST doc didn't rendered properly, but that's
not the case here.

> Hunh, everywhere I'd looked didn't have the "()" (which seems
> redundant). The blank line was entirely aesthetics for me. If it's
> supposed to be without a blank, I can fix it up everwhere.

So, I think this is more of a territory of preference or consistency
rather than that of correctness.  Those extra blank lines can be confusing
as most people expect it in front of description part. says Kees is the sole maintainer of overflow.h, so
it's his call, I guess.

        Thanks, Akira

Powered by blists - more mailing lists