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  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:   Mon, 26 Sep 2022 20:02:16 -0700
From:   Kees Cook <keescook@...omium.org>
To:     Akira Yokosawa <akiyks@...il.com>
Cc:     Matthew Wilcox <willy@...radead.org>,
        Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org,
        linux-hardening@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH] overflow: Fix kern-doc markup for functions

On Tue, Sep 27, 2022 at 11:53:38AM +0900, Akira Yokosawa wrote:
> Hi,
> 
> 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".

Out of curiosity, why is the trailing "()" part of the standard
template? Isn't it redundant? Or is trying to help differentiate between
things that are non-callable? (i.e. a variable, etc.)

> > 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.
> 
> get_maintainer.pl says Kees is the sole maintainer of overflow.h, so
> it's his call, I guess.

Well, maintainer or not, I want to make sure stuff is as readable as
possible by everyone else too. :) I'm happy to skip the blank lines!

-- 
Kees Cook

Powered by blists - more mailing lists