Re: Return: vs Returns:

[Mike Rapoport <rppt@linux.ibm.com>]

Hi Markus,

On Thu, Feb 07, 2019 at 04:58:17PM +0100, Markus Heiser wrote:
> Am 07.02.19 um 16:30 schrieb Mike Rapoport:
> >On Thu, Feb 07, 2019 at 05:59:24AM -0800, Matthew Wilcox wrote:
> >>
> >>This seems to be an extremely common mistake to make (indeed, almost
> >>3000 occurrences of 'Returns:' vs 5300 occurrences of 'Return:').
> >Add to that ~1000 '@return:'.
> >
> >But scripts/kernel-doc does not really care:
> >
> >	} elsif ($newsection =~ m/^return?$/i) {
> >	    $newsection = $section_return;
> >	} elsif ($newsection =~ m/^\@return$/) {
> >	    # special: @return is a section, not a param description
> >	    $newsection = $section_return;
> >	}
> 
> 
> Hi Mike, I only got this fragment of the thread, for me it is not absolutly
> clear what the problem is .. I guess it is about the "Return" section in
> kernel-doc comments, right?

Yeah, I think we can make kernel-doc more strict about it to start with.
 
> The snippet from you above is the right point, it should work like it is
> described here:
> 
>   https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#return-values
> 
> doesn't it? Or did you just want a checkpatch ...
> 
> >>Could we have a checkpatch warning for it?
> >
> >Does checkpatch checks the kernel-doc parts at all?
> 
> No.  I guess there are to many places to fail / to hard to put someone in
> charge.  E.g. if you do include a single kernel-doc comment from a source all
> kernel-docs in the source will be parsed and may produce (error/warning)
> essages.  What we have, are some targets:
> 
> -linkcheckdocs
>  check for broken external links (will connect to external hosts)
> 
> - refcheckdocs
>   check for references to non-existing files under Documentation

Right, but these should be checked explicitly and I doubt many people do it
before submitting patches. OTOH, checkpatch is something that's widely used
and if it had verified the kernel-doc parts, more comments would be
following the convention.
 
> -- Markus --
> 
> >
> >>----- Forwarded message from Matthew Wilcox <willy@infradead.org> -----
> >>
> >>On Wed, Jan 16, 2019 at 04:59:27PM +0000, Christophe Leroy wrote:
> >>>  v3: Moved 'Returns:" comment after description.
> >>>      Explained in the commit log why the function is defined static inline
> >>>
> >>>  v2: Added "Returns:" comment and removed probe_user_address()
> >>
> >>The correct spelling is 'Return:', not 'Returns:':
> >>
> >>Return values
> >>~~~~~~~~~~~~
> >>
> >>The return value, if any, should be described in a dedicated section
> >>named ``Return``.
> >>
> >>----- End forwarded message -----
> >>
> >
> 

-- 
Sincerely yours,
Mike.