Re: Return: vs Returns:

[Markus Heiser <markus.heiser@darmarit.de>]

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;

Is there really a need to be standardize this? From the list above I think
there are only a few where it fails.

-- Markus --