Re: [RFC PATCH v1 3/6] kernel-doc: add kerneldoc-lint command

[Jani Nikula]

On Wed, 25 Jan 2017, Daniel Vetter <daniel@xxxxxxxx> wrote:
> On Tue, Jan 24, 2017 at 08:52:41PM +0100, Markus Heiser wrote:
>> this patch adds a command to lint kernel-doc comments.::
>> 
>>   scripts/kerneldoc-lint --help
>> 
>> The lint check include (only) kernel-doc rules described at [1]. It
>> does not check against reST (sphinx-doc) markup used in the kernel-doc
>> comments.  Since reST markups could include depencies to the build-
>> context (e.g. open/closed refs) only a sphinx-doc build can check the
>> reST markup in the context of the document it builds.
>> 
>> With 'kerneldoc-lint' command you can check a single file or a whole
>> folder, e.g:
>> 
>>   scripts/kerneldoc-lint include/drm
>>   ...
>>   scripts/kerneldoc-lint include/media/media-device.h
>> 
>> The lint-implementation is a part of the parser module (kernel_doc.py).
>> The comandline implementation consist only of a argument parser ('opts')
>> which calls the kernel-doc parser with a 'NullTranslator'.::
>> 
>>    parser = kerneldoc.Parser(opts, kerneldoc.NullTranslator())
>> 
>> Latter is also a small example of how-to implement kernel-doc
>> applications with the kernel-doc parser architecture.
>> 
>> [1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#writing-kernel-doc-comments
>> 
>> Signed-off-by: Markus Heiser <markus.heiser@xxxxxxxxxxx>
>
> Didn't we have a patch from Jani to gives us a make target doing this? I
> think that'd be even neater ...

Yes, see below. It's simplistic and it has an external dependency, but
it got the job done. And it does not depend on Sphinx; it's just a
kernel-doc and rst lint, not Sphinx lint. Whether that's a good or a bad
thing is debatable.

Anyway, I do think the approach of making 'make CHECK=the-tool C=1' work
is what we should aim at. Markus' patch could probably be made to do
that by accepting the same arguments that are passed to compilers.

BR,
Jani.