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