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 ...
-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
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
