#!/usr/bin/env python3 # SPDX-License-Identifier: GPL-2.0 # Copyright(c) 2025: Mauro Carvalho Chehab <[email protected]>. # # pylint: disable=C0103,R0912,R0914,R0915 # # NOTE: While kernel-doc requires at least version 3.6 to run, the # command line should work with Python 3.2+ (tested with 3.4). # The rationale is that it shall fail gracefully during Kernel # compilation with older Kernel versions. Due to that: # - encoding line is needed here; # - f-strings cannot be used in this file. # - libraries that require newer versions can only be included # after the Python version has been checked. # # Converted from the kernel-doc script originally written in Perl # under GPLv2, copyrighted since 1998 by the following authors: # # Aditya Srivastava <[email protected]> # Akira Yokosawa <[email protected]> # Alexander A. Klimov <[email protected]> # Alexander Lobakin <[email protected]> # André Almeida <[email protected]> # Andy Shevchenko <[email protected]> # Anna-Maria Behnsen <[email protected]> # Armin Kuster <[email protected]> # Bart Van Assche <[email protected]> # Ben Hutchings <[email protected]> # Borislav Petkov <[email protected]> # Chen-Yu Tsai <[email protected]> # Coco Li <[email protected]> # Conchúr Navid <[email protected]> # Daniel Santos <[email protected]> # Danilo Cesar Lemes de Paula <[email protected]> # Dan Luedtke <[email protected]> # Donald Hunter <[email protected]> # Gabriel Krisman Bertazi <[email protected]> # Greg Kroah-Hartman <[email protected]> # Harvey Harrison <[email protected]> # Horia Geanta <[email protected]> # Ilya Dryomov <[email protected]> # Jakub Kicinski <[email protected]> # Jani Nikula <[email protected]> # Jason Baron <[email protected]> # Jason Gunthorpe <[email protected]> # Jérémy Bobbio <[email protected]> # Johannes Berg <[email protected]> # Johannes Weiner <[email protected]> # Jonathan Cameron <[email protected]> # Jonathan Corbet <[email protected]> # Jonathan Neuschäfer <[email protected]> # Kamil Rytarowski <[email protected]> # Kees Cook <[email protected]> # Laurent Pinchart <[email protected]> # Levin, Alexander (Sasha Levin) <[email protected]> # Linus Torvalds <[email protected]> # Lucas De Marchi <[email protected]> # Mark Rutland <[email protected]> # Markus Heiser <[email protected]> # Martin Waitz <[email protected]> # Masahiro Yamada <[email protected]> # Matthew Wilcox <[email protected]> # Mauro Carvalho Chehab <[email protected]> # Michal Wajdeczko <[email protected]> # Michael Zucchi # Mike Rapoport <[email protected]> # Niklas Söderlund <[email protected]> # Nishanth Menon <[email protected]> # Paolo Bonzini <[email protected]> # Pavan Kumar Linga <[email protected]> # Pavel Pisa <[email protected]> # Peter Maydell <[email protected]> # Pierre-Louis Bossart <[email protected]> # Randy Dunlap <[email protected]> # Richard Kennedy <[email protected]> # Rich Walker <[email protected]> # Rolf Eike Beer <[email protected]> # Sakari Ailus <[email protected]> # Silvio Fricke <[email protected]> # Simon Huggins # Tim Waugh <[email protected]> # Tomasz Warniełło <[email protected]> # Utkarsh Tripathi <[email protected]> # [email protected] <[email protected]> # Vegard Nossum <[email protected]> # Will Deacon <[email protected]> # Yacine Belkadi <[email protected]> # Yujie Liu <[email protected]> """ Print formatted kernel documentation to stdout. Read C language source or header FILEs, extract embedded documentation comments, and print formatted documentation to standard output. The documentation comments are identified by the ``/**`` opening comment mark. See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. """ import argparse import logging import os import sys # Import Python modules LIB_DIR = "../lib/python" SRC_DIR = os.path.dirname(os.path.realpath(__file__)) sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) WERROR_RETURN_CODE = 3 DESC = """ Read C language source or header FILEs, extract embedded documentation comments, and print formatted documentation to standard output. The documentation comments are identified by the "/**" opening comment mark. See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. """ EXPORT_FILE_DESC = """ Specify an additional FILE in which to look for EXPORT_SYMBOL information. May be used multiple times. """ EXPORT_DESC = """ Only output documentation for symbols that have been exported using EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE. """ INTERNAL_DESC = """ Only output documentation for symbols that have NOT been exported using EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE. """ FUNCTION_DESC = """ Only output documentation for the given function or DOC: section title. All other functions and DOC: sections are ignored. May be used multiple times. """ NOSYMBOL_DESC = """ Exclude the specified symbol from the output documentation. May be used multiple times. """ FILES_DESC = """ Header and C source files to be parsed. """ WARN_CONTENTS_BEFORE_SECTIONS_DESC = """ Warn if there are contents before sections (deprecated). This option is kept just for backward-compatibility, but it does nothing, neither here nor at the original Perl script. """ EPILOG = """ The return value is: - 0: success or Python version is not compatible with kernel-doc. If -Werror is not used, it will also return 0 if there are issues at kernel-doc markups; - 1: an abnormal condition happened; - 2: argparse issued an error; - 3: When -Werror is used, it means that one or more unfiltered parse warnings happened. """ class MsgFormatter(logging.Formatter): """ Helper class to capitalize errors and warnings, the same way the venerable (now retired) kernel-doc.pl used to do. """ def format(self, record): record.levelname = record.levelname.capitalize() return logging.Formatter.format(self, record) def main(): """ Main program. """ parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter, description=DESC, epilog=EPILOG) # # Normal arguments # parser.add_argument("-v", "-verbose", "--verbose", action="store_true", help="Verbose output, more warnings and other information.") parser.add_argument("-d", "-debug", "--debug", action="store_true", help="Enable debug messages") parser.add_argument("-M", "-modulename", "--modulename", default="Kernel API", help="Allow setting a module name at the output.") parser.add_argument("-l", "-enable-lineno", "--enable_lineno", action="store_true", help="Enable line number output (only in ReST mode)") # # Arguments to control the warning behavior # parser.add_argument("-Wreturn", "--wreturn", action="store_true", help="Warns about the lack of a return markup on functions.") parser.add_argument("-Wshort-desc", "-Wshort-description", "--wshort-desc", action="store_true", help="Warns if initial short description is missing") parser.add_argument("-Wcontents-before-sections", "--wcontents-before-sections", action="store_true", help=WARN_CONTENTS_BEFORE_SECTIONS_DESC) parser.add_argument("-Wall", "--wall", action="store_true", help="Enable all types of warnings") parser.add_argument("-Werror", "--werror", action="store_true", help="Treat warnings as errors.") parser.add_argument("-export-file", "--export-file", action='append', help=EXPORT_FILE_DESC) # # Output format mutually-exclusive group # out_group = parser.add_argument_group("Output format selection (mutually exclusive)") out_fmt = out_group.add_mutually_exclusive_group() out_fmt.add_argument("-m", "-man", "--man", action="store_true", help="Output troff manual page format.") out_fmt.add_argument("-r", "-rst", "--rst", action="store_true", help="Output reStructuredText format (default).") out_fmt.add_argument("-N", "-none", "--none", action="store_true", help="Do not output documentation, only warnings.") # # Output selection mutually-exclusive group # sel_group = parser.add_argument_group("Output selection (mutually exclusive)") sel_mut = sel_group.add_mutually_exclusive_group() sel_mut.add_argument("-e", "-export", "--export", action='store_true', help=EXPORT_DESC) sel_mut.add_argument("-i", "-internal", "--internal", action='store_true', help=INTERNAL_DESC) sel_mut.add_argument("-s", "-function", "--symbol", action='append', help=FUNCTION_DESC) # # Those are valid for all 3 types of filter # parser.add_argument("-n", "-nosymbol", "--nosymbol", action='append', help=NOSYMBOL_DESC) parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections", action='store_true', help="Don't output DOC sections") parser.add_argument("files", metavar="FILE", nargs="+", help=FILES_DESC) args = parser.parse_args() if args.wall: args.wreturn = True args.wshort_desc = True args.wcontents_before_sections = True logger = logging.getLogger() if not args.debug: logger.setLevel(logging.INFO) else: logger.setLevel(logging.DEBUG) formatter = MsgFormatter('%(levelname)s: %(message)s') handler = logging.StreamHandler() handler.setFormatter(formatter) logger.addHandler(handler) python_ver = sys.version_info[:2] if python_ver < (3,6): # # Depending on the Kernel configuration, kernel-doc --none is called at # build time. As we don't want to break compilation due to the # usage of an old Python version, return 0 here. # if args.none: logger.error("Python 3.6 or later is required by kernel-doc. Skipping checks") sys.exit(0) sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.") if python_ver < (3,7): logger.warning("Python 3.7 or later is required for correct results") # # Import kernel-doc libraries only after checking the Python version # from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415 from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415 if args.man: out_style = ManFormat(modulename=args.modulename) elif args.none: out_style = None else: out_style = RestFormat() kfiles = KernelFiles(verbose=args.verbose, out_style=out_style, werror=args.werror, wreturn=args.wreturn, wshort_desc=args.wshort_desc, wcontents_before_sections=args.wcontents_before_sections) kfiles.parse(args.files, export_file=args.export_file) for t in kfiles.msg(enable_lineno=args.enable_lineno, export=args.export, internal=args.internal, symbol=args.symbol, nosymbol=args.nosymbol, export_file=args.export_file, no_doc_sections=args.no_doc_sections): msg = t[1] if msg: print(msg) error_count = kfiles.errors if not error_count: sys.exit(0) if args.werror: print("%s warnings as errors" % error_count) # pylint: disable=C0209 sys.exit(WERROR_RETURN_CODE) if args.verbose: print("%s errors" % error_count) # pylint: disable=C0209 sys.exit(0) # # Call main method # if __name__ == "__main__": main()
