#!/usr/bin/env python3# SPDX-License-Identifier: GPL-2.0# Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@kernel.org>.## 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;#       - no f-strings can be used on this file.#       - the libraries that require newer versions can only be included#         after Python version is checked. # Converted from the kernel-doc script originally written in Perl# under GPLv2, copyrighted since 1998 by the following authors:##    Aditya Srivastava <yashsri421@gmail.com>#    Akira Yokosawa <akiyks@gmail.com>#    Alexander A. Klimov <grandmaster@al2klimov.de>#    Alexander Lobakin <aleksander.lobakin@intel.com>#    André Almeida <andrealmeid@igalia.com>#    Andy Shevchenko <andriy.shevchenko@linux.intel.com>#    Anna-Maria Behnsen <anna-maria@linutronix.de>#    Armin Kuster <akuster@mvista.com>#    Bart Van Assche <bart.vanassche@sandisk.com>#    Ben Hutchings <ben@decadent.org.uk>#    Borislav Petkov <bbpetkov@yahoo.de>#    Chen-Yu Tsai <wenst@chromium.org>#    Coco Li <lixiaoyan@google.com>#    Conchúr Navid <conchur@web.de>#    Daniel Santos <daniel.santos@pobox.com>#    Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>#    Dan Luedtke <mail@danrl.de>#    Donald Hunter <donald.hunter@gmail.com>#    Gabriel Krisman Bertazi <krisman@collabora.co.uk>#    Greg Kroah-Hartman <gregkh@linuxfoundation.org>#    Harvey Harrison <harvey.harrison@gmail.com>#    Horia Geanta <horia.geanta@freescale.com>#    Ilya Dryomov <idryomov@gmail.com>#    Jakub Kicinski <kuba@kernel.org>#    Jani Nikula <jani.nikula@intel.com>#    Jason Baron <jbaron@redhat.com>#    Jason Gunthorpe <jgg@nvidia.com>#    Jérémy Bobbio <lunar@debian.org>#    Johannes Berg <johannes.berg@intel.com>#    Johannes Weiner <hannes@cmpxchg.org>#    Jonathan Cameron <Jonathan.Cameron@huawei.com>#    Jonathan Corbet <corbet@lwn.net>#    Jonathan Neuschäfer <j.neuschaefer@gmx.net>#    Kamil Rytarowski <n54@gmx.com>#    Kees Cook <kees@kernel.org>#    Laurent Pinchart <laurent.pinchart@ideasonboard.com>#    Levin, Alexander (Sasha Levin) <alexander.levin@verizon.com>#    Linus Torvalds <torvalds@linux-foundation.org>#    Lucas De Marchi <lucas.demarchi@profusion.mobi>#    Mark Rutland <mark.rutland@arm.com>#    Markus Heiser <markus.heiser@darmarit.de>#    Martin Waitz <tali@admingilde.org>#    Masahiro Yamada <masahiroy@kernel.org>#    Matthew Wilcox <willy@infradead.org>#    Mauro Carvalho Chehab <mchehab+huawei@kernel.org>#    Michal Wajdeczko <michal.wajdeczko@intel.com>#    Michael Zucchi#    Mike Rapoport <rppt@linux.ibm.com>#    Niklas Söderlund <niklas.soderlund@corigine.com>#    Nishanth Menon <nm@ti.com>#    Paolo Bonzini <pbonzini@redhat.com>#    Pavan Kumar Linga <pavan.kumar.linga@intel.com>#    Pavel Pisa <pisa@cmp.felk.cvut.cz>#    Peter Maydell <peter.maydell@linaro.org>#    Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>#    Randy Dunlap <rdunlap@infradead.org>#    Richard Kennedy <richard@rsk.demon.co.uk>#    Rich Walker <rw@shadow.org.uk>#    Rolf Eike Beer <eike-kernel@sf-tec.de>#    Sakari Ailus <sakari.ailus@linux.intel.com>#    Silvio Fricke <silvio.fricke@gmail.com>#    Simon Huggins#    Tim Waugh <twaugh@redhat.com>#    Tomasz Warniełło <tomasz.warniello@gmail.com>#    Utkarsh Tripathi <utripathi2002@gmail.com>#    valdis.kletnieks@vt.edu <valdis.kletnieks@vt.edu>#    Vegard Nossum <vegard.nossum@oracle.com>#    Will Deacon <will.deacon@arm.com>#    Yacine Belkadi <yacine.belkadi.1@gmail.com>#    Yujie Liu <yujie.liu@intel.com> """kernel_doc========== Print formatted kernel documentation to stdout Read C language source or header FILEs, extract embeddeddocumentation comments, and print formatted documentationto standard output. The documentation comments are identified by the "/**"opening comment mark. See Documentation/doc-guide/kernel-doc.rst for thedocumentation comment syntax.""" import argparseimport loggingimport osimport sys # Import Python modules LIB_DIR = "../tools/lib/python"SRC_DIR = os.path.dirname(os.path.realpath(__file__)) sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) 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 the symbols that have beenexported using EXPORT_SYMBOL() and related macros in any inputFILE or -export-file FILE.""" INTERNAL_DESC = """Only output documentation for the symbols that have NOT beenexported using EXPORT_SYMBOL() and related macros in any inputFILE or -export-file FILE.""" FUNCTION_DESC = """Only output documentation for the given function or DOC: sectiontitle. 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 = """Warns 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."""  class MsgFormatter(logging.Formatter):    """Helper class to format warnings on a similar way to kernel-doc.pl"""     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)     # 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 outputt 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 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 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(error_count)     if args.verbose:        print("%s errors" % error_count)                # pylint: disable=C0209     if args.none:        sys.exit(0)     sys.exit(error_count)  # Call main methodif __name__ == "__main__":    main()