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 <[email protected]> -----
> >>
> >>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.
