Re: Return: vs Returns:

[Jani Nikula <jani.nikula@linux.intel.com>]

On Thu, 07 Feb 2019, Joe Perches <joe@perches.com> wrote:
> On Thu, 2019-02-07 at 18:58 +0100, Markus Heiser wrote:
>> Am 07.02.19 um 18:50 schrieb Joe Perches:
>> > On Thu, 2019-02-07 at 09:34 -0800, Matthew Wilcox wrote:
>> > > On Thu, Feb 07, 2019 at 09:31:20AM -0800, Joe Perches wrote:
>> > > > It's not clear to me what you are asking checkpatch to do here.
>> > > > 
>> > > > It may be reasonable for checkpatch to invoke kernel-doc on some
>> > > > portion of a patch, but I'm not sure how valuable it will be.
>> > > 
>> > > I was just hoping to match:
>> > > 
>> > >   * Returns:
>> > > 
>> > > Or to quote it properly for regexes ...
>> > > 
>> > > ^ +\* *Returns:
>> > > 
>> > > (I think ...)
>> > > 
>> > > I can't see that matching C or assembler.
>> > 
>> > checkpatch doesn't attempt to enforce any formatting standard
>> > on kernel-doc comments.
>> > 
>> > There doesn't seem to be much standardization for kernel-doc
>> > in the first place.
>> > 
>> > Just for the * return: case:
>> > 
>> > $ git grep -P -i '^\s*\*\s*returns?\s*:' -- '*.[ch]' | \
>> >    grep -P -oh -i '\*\s*returns?\s*:' | \
>> >    sort | uniq -c | sort -rn
>> >     5153 * Return:
>> >     2534 * Returns:
>> >     1077 * RETURN:
>> >      358 * RETURNS:
>> >      173 *	RETURNS:
>> >      171 * returns:
>> >      153 * return:
>> >      148 * Return :
>> >       72 * Returns :
>> >       61 *	Returns:
>> >       37 *  Returns:
>> >       30 *  returns:
>> >       27 *  return:
>> >       22 *	Return:
>> >       20 * Returns  :
>> >       19 *  Return:
>> >       15 *  RETURNS:
>> >       11 *           return:
>> >        6 * return :
>> >        6 *	return:
>> >        5 * returns :
>> >        3 *Returns:
>> >        3 * Returns	:
>> >        3 * 	returns:
>> >        2 *RETURNS:
>> >        2 *     Returns:
>> >        2 *      Returns:
>> >        2 *	returns:
>> >        2 * RETURN :
>> >        2 *      Return:
>> >        2 * 	Return:
>> >        2 *	return :
>> >        2 *		return:
>> >        1 *   RETURNS:
>> >        1 * RETURNs:
>> >        1 *   Returns:
>> >        1 *    Returns:
>> >        1 * 	Returns:
>> >        1 *  RETURN:
>> >        1 *   Return:
>> >        1 *    Return:
>> >        1 * return   :
>> > 
>> > I think standarization is more something that scripts/kernel-doc
>> > could or should do.
>> 
>> BTW: kernel-doc parser accept 'return' and 'returns':
>> 
>>      } elsif ($newsection =~ m/^return?$/i) {
>>          $newsection = $section_return;
>
> That regex doesn't look like it does accept returns.

Yeah that copy-paste is from who knows where, kernel-doc DTRT.

> That looks like it accepts either retur or return.
> I believe that would need to be
>
> 	$newsection =~ m/returns?$/i
>
>> Is there really a need to be standardize this?
>
> I generally doubt it.

I ran a regex similar to yours (there's also "@returns?:") way back when
adding Sphinx support, and my conclusion was trying to standardize this
is futile. Sure we can document and encourage one (I chose "Return:"
based on the grep popularity contest) but trying to change everything is
just unnecessary busywork.

However, kernel-doc does standardize the *output* for more uniform and
nicer looking results.


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Graphics Center