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

[Daniel Vetter <daniel@ffwll.ch>]

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@darmarit.de>

Didn't we have a patch from Jani to gives us a make target doing this? I
think that'd be even neater ...
-Daniel

> ---
>  Documentation/sphinx/lint.py | 121 +++++++++++++++++++++++++++++++++++++++++++
>  scripts/kerneldoc-lint       |  11 ++++
>  2 files changed, 132 insertions(+)
>  create mode 100755 Documentation/sphinx/lint.py
>  create mode 100755 scripts/kerneldoc-lint
> 
> diff --git a/Documentation/sphinx/lint.py b/Documentation/sphinx/lint.py
> new file mode 100755
> index 0000000..5a0128f
> --- /dev/null
> +++ b/Documentation/sphinx/lint.py
> @@ -0,0 +1,121 @@
> +#!/usr/bin/env python3
> +# -*- coding: utf-8; mode: python -*-
> +# pylint: disable=C0103
> +
> +u"""
> +    lint
> +    ~~~~
> +
> +    Implementation of the ``kerneldoc-lint`` command.
> +
> +    :copyright:  Copyright (C) 2016  Markus Heiser
> +    :license:    GPL Version 2, June 1991 see Linux/COPYING for details.
> +
> +    The ``kernel-doclint`` command *lints* documentation from Linux kernel's
> +    source code comments, see ``--help``::
> +
> +        $ kernel-lintdoc --help
> +
> +    .. note::
> +
> +       The kernel-lintdoc command is under construction, no stable release
> +       yet. The command-line arguments might be changed/extended in the near
> +       future."""
> +
> +# ------------------------------------------------------------------------------
> +# imports
> +# ------------------------------------------------------------------------------
> +
> +import sys
> +import argparse
> +
> +#import six
> +
> +from fspath import FSPath
> +import kernel_doc as kerneldoc
> +
> +# ------------------------------------------------------------------------------
> +# config
> +# ------------------------------------------------------------------------------
> +
> +MSG    = lambda msg: sys.__stderr__.write("INFO : %s\n" % msg)
> +ERR    = lambda msg: sys.__stderr__.write("ERROR: %s\n" % msg)
> +FATAL  = lambda msg: sys.__stderr__.write("FATAL: %s\n" % msg)
> +
> +epilog = u"""This implementation of uses the kernel-doc parser
> +from the linuxdoc extension, for detail informations read
> +http://return42.github.io/sphkerneldoc/books/kernel-doc-HOWTO"""
> +
> +# ------------------------------------------------------------------------------
> +def main():
> +# ------------------------------------------------------------------------------
> +
> +    CLI = argparse.ArgumentParser(
> +        description = ("Lint *kernel-doc* comments from source code")
> +        , epilog = epilog
> +        , formatter_class=argparse.ArgumentDefaultsHelpFormatter)
> +
> +    CLI.add_argument(
> +        "srctree"
> +        , help    = "File or folder of source code."
> +        , type    = lambda x: FSPath(x).ABSPATH)
> +
> +    CLI.add_argument(
> +        "--sloppy"
> +        , action  = "store_true"
> +        , help    = "Sloppy linting, reports only severe errors.")
> +
> +    CLI.add_argument(
> +        "--markup"
> +        , choices = ["reST", "kernel-doc"]
> +        , default = "reST"
> +        , help    = (
> +            "Markup of the comments. Change this option only if you know"
> +            " what you do. New comments must be marked up with reST!"))
> +
> +    CLI.add_argument(
> +        "--verbose", "-v"
> +        , action  = "store_true"
> +        , help    = "verbose output with log messages to stderr" )
> +
> +    CLI.add_argument(
> +        "--debug"
> +        , action  = "store_true"
> +        , help    = "debug messages to stderr" )
> +
> +    CMD = CLI.parse_args()
> +    kerneldoc.DEBUG = CMD.debug
> +    kerneldoc.VERBOSE = CMD.verbose
> +
> +    if not CMD.srctree.EXISTS:
> +        ERR("%s does not exists or is not a folder" % CMD.srctree)
> +        sys.exit(42)
> +
> +    if CMD.srctree.ISDIR:
> +        for fname in CMD.srctree.reMatchFind(r"^.*\.[ch]$"):
> +            if fname.startswith(CMD.srctree/"Documentation"):
> +                continue
> +            lintdoc_file(fname, CMD)
> +    else:
> +        fname = CMD.srctree
> +        CMD.srctree = CMD.srctree.DIRNAME
> +        lintdoc_file(fname, CMD)
> +
> +# ------------------------------------------------------------------------------
> +def lintdoc_file(fname, CMD):
> +# ------------------------------------------------------------------------------
> +
> +    fname = fname.relpath(CMD.srctree)
> +    opts = kerneldoc.ParseOptions(
> +        rel_fname       = fname
> +        , src_tree      = CMD.srctree
> +        , verbose_warn  = not (CMD.sloppy)
> +        , markup        = CMD.markup )
> +
> +    parser = kerneldoc.Parser(opts, kerneldoc.NullTranslator())
> +    try:
> +        parser.parse()
> +    except Exception: # pylint: disable=W0703
> +        FATAL("kernel-doc comments markup of %s seems buggy / can't parse" % opts.fname)
> +        return
> +
> diff --git a/scripts/kerneldoc-lint b/scripts/kerneldoc-lint
> new file mode 100755
> index 0000000..5109f7b
> --- /dev/null
> +++ b/scripts/kerneldoc-lint
> @@ -0,0 +1,11 @@
> +#!/usr/bin/python
> +
> +import sys
> +from os import path
> +
> +linuxdoc = path.abspath(path.join(path.dirname(__file__), '..'))
> +linuxdoc = path.join(linuxdoc, 'Documentation', 'sphinx')
> +sys.path.insert(0, linuxdoc)
> +
> +import lint
> +lint.main()
> -- 
> 2.7.4
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch