Re: [PATCH] overflow: Fix kern-doc markup for functions

Kees Cook
2022-09-26T21:09:19Z

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