kernel / scripts / kernel-doc.py

#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-2.0
# Copyright(c) 2025: Mauro Carvalho Chehab <[e-mail]>.
#
# 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 <[e-mail]>
#    Akira Yokosawa <[e-mail]>
#    Alexander A. Klimov <[e-mail]>
#    Alexander Lobakin <[e-mail]>
#    André Almeida <[e-mail]>
#    Andy Shevchenko <[e-mail]>
#    Anna-Maria Behnsen <[e-mail]>
#    Armin Kuster <[e-mail]>
#    Bart Van Assche <[e-mail]>
#    Ben Hutchings <[e-mail]>
#    Borislav Petkov <[e-mail]>
#    Chen-Yu Tsai <[e-mail]>
#    Coco Li <[e-mail]>
#    Conchúr Navid <[e-mail]>
#    Daniel Santos <[e-mail]>
#    Danilo Cesar Lemes de Paula <[e-mail]>
#    Dan Luedtke <[e-mail]>
#    Donald Hunter <[e-mail]>
#    Gabriel Krisman Bertazi <[e-mail]>
#    Greg Kroah-Hartman <[e-mail]>
#    Harvey Harrison <[e-mail]>
#    Horia Geanta <[e-mail]>
#    Ilya Dryomov <[e-mail]>
#    Jakub Kicinski <[e-mail]>
#    Jani Nikula <[e-mail]>
#    Jason Baron <[e-mail]>
#    Jason Gunthorpe <[e-mail]>
#    Jérémy Bobbio <[e-mail]>
#    Johannes Berg <[e-mail]>
#    Johannes Weiner <[e-mail]>
#    Jonathan Cameron <[e-mail]>
#    Jonathan Corbet <[e-mail]>
#    Jonathan Neuschäfer <[e-mail]>
#    Kamil Rytarowski <[e-mail]>
#    Kees Cook <[e-mail]>
#    Laurent Pinchart <[e-mail]>
#    Levin, Alexander (Sasha Levin) <[e-mail]>
#    Linus Torvalds <[e-mail]>
#    Lucas De Marchi <[e-mail]>
#    Mark Rutland <[e-mail]>
#    Markus Heiser <[e-mail]>
#    Martin Waitz <[e-mail]>
#    Masahiro Yamada <[e-mail]>
#    Matthew Wilcox <[e-mail]>
#    Mauro Carvalho Chehab <[e-mail]>
#    Michal Wajdeczko <[e-mail]>
#    Michael Zucchi
#    Mike Rapoport <[e-mail]>
#    Niklas Söderlund <[e-mail]>
#    Nishanth Menon <[e-mail]>
#    Paolo Bonzini <[e-mail]>
#    Pavan Kumar Linga <[e-mail]>
#    Pavel Pisa <[e-mail]>
#    Peter Maydell <[e-mail]>
#    Pierre-Louis Bossart <[e-mail]>
#    Randy Dunlap <[e-mail]>
#    Richard Kennedy <[e-mail]>
#    Rich Walker <[e-mail]>
#    Rolf Eike Beer <[e-mail]>
#    Sakari Ailus <[e-mail]>
#    Silvio Fricke <[e-mail]>
#    Simon Huggins
#    Tim Waugh <[e-mail]>
#    Tomasz Warniełło <[e-mail]>
#    Utkarsh Tripathi <[e-mail]>
#    [e-mail] <[e-mail]>
#    Vegard Nossum <[e-mail]>
#    Will Deacon <[e-mail]>
#    Yacine Belkadi <[e-mail]>
#    Yujie Liu <[e-mail]>

"""
kernel_doc
==========

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 = "../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 been
exported using EXPORT_SYMBOL() and related macros in any input
FILE or -export-file FILE.
"""

INTERNAL_DESC = """
Only output documentation for the 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 = """
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 method
if __name__ == "__main__":
    main()