On Thu, 07 Feb 2019, Joe Perches <joe@xxxxxxxxxxx> 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
