Re: Return: vs Returns:

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

On Thu, Feb 07, 2019 at 06:33:34PM +0100, Markus Heiser wrote:
> 
> Am 07.02.19 um 17:18 schrieb Mike Rapoport:
> >>>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.
> 
> I'am with you, but I do not have any clue how to solve this Gordian Knot
> faithful and without massive collateral damage / sorry :|
> 
> The only thing I know, we have the -none option:
> 
> $ ./scripts/kernel-doc -none ./include/media/cec.h
> ./include/media/cec.h:51: warning: Function parameter or member 'lock' not
> described in 'cec_devnode'
> 
> But this is nothing more than noise if the patch does not touch cec_devnode.
> And there is another problem I see, if we want to check refs ...

Well, the case when a patch changes function parameters but forgets to
update the kernel-doc part is particularly annoying.
I believe it's possible to match function parameter changes with the
corresponding kernel-doc changes (or lack of them).
 
> >> -linkcheckdocs
> >>   check for broken external links (will connect to external hosts)
> >>
> >> - refcheckdocs
> >>    check for references to non-existing files under Documentation
> 
> The refs are solved late in the sphinx build process when .rst files and
> kernel-doc comments come together .. so we need sphinx for checkpatch,
> I gues this is a no-go (?)
> 
> -- Markus --
> 

-- 
Sincerely yours,
Mike.