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

[Markus Heiser <markus.heiser@darmarit.de>]

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>
---
 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