Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Mon, 26 Sep 2022 14:09:10 -0700
From:   Kees Cook <keescook@chromium.org>
To:     Matthew Wilcox <willy@infradead.org>
Cc:     Jonathan Corbet <corbet@lwn.net>,
        Akira Yokosawa <akiyks@gmail.com>, linux-doc@vger.kernel.org,
        linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH] overflow: Fix kern-doc markup for functions
Message-ID: <202209261408.59F78C0D@keescook>
References: <20220926194713.1806917-1-keescook@chromium.org>
 <YzIUS/+H2YA7RBvA@casper.infradead.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <YzIUS/+H2YA7RBvA@casper.infradead.org>
Precedence: bulk

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.
> 
> I don't usually complain about people getting that wrong, but when
> people correct it to be wrong ...

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.

-- 
Kees Cook