kernel-doc.py

  1#!/usr/bin/env python3
  2# SPDX-License-Identifier: GPL-2.0
  3# Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@kernel.org>.
  4#
  5# pylint: disable=C0103,R0912,R0914,R0915
  6
  7# NOTE: While kernel-doc requires at least version 3.6 to run, the
  8#       command line should work with Python 3.2+ (tested with 3.4).
  9#       The rationale is that it shall fail gracefully during Kernel
 10#       compilation with older Kernel versions. Due to that:
 11#       - encoding line is needed here;
 12#       - no f-strings can be used on this file.
 13#       - the libraries that require newer versions can only be included
 14#         after Python version is checked.
 15
 16# Converted from the kernel-doc script originally written in Perl
 17# under GPLv2, copyrighted since 1998 by the following authors:
 18#
 19#    Aditya Srivastava <yashsri421@gmail.com>
 20#    Akira Yokosawa <akiyks@gmail.com>
 21#    Alexander A. Klimov <grandmaster@al2klimov.de>
 22#    Alexander Lobakin <aleksander.lobakin@intel.com>
 23#    André Almeida <andrealmeid@igalia.com>
 24#    Andy Shevchenko <andriy.shevchenko@linux.intel.com>
 25#    Anna-Maria Behnsen <anna-maria@linutronix.de>
 26#    Armin Kuster <akuster@mvista.com>
 27#    Bart Van Assche <bart.vanassche@sandisk.com>
 28#    Ben Hutchings <ben@decadent.org.uk>
 29#    Borislav Petkov <bbpetkov@yahoo.de>
 30#    Chen-Yu Tsai <wenst@chromium.org>
 31#    Coco Li <lixiaoyan@google.com>
 32#    Conchúr Navid <conchur@web.de>
 33#    Daniel Santos <daniel.santos@pobox.com>
 34#    Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
 35#    Dan Luedtke <mail@danrl.de>
 36#    Donald Hunter <donald.hunter@gmail.com>
 37#    Gabriel Krisman Bertazi <krisman@collabora.co.uk>
 38#    Greg Kroah-Hartman <gregkh@linuxfoundation.org>
 39#    Harvey Harrison <harvey.harrison@gmail.com>
 40#    Horia Geanta <horia.geanta@freescale.com>
 41#    Ilya Dryomov <idryomov@gmail.com>
 42#    Jakub Kicinski <kuba@kernel.org>
 43#    Jani Nikula <jani.nikula@intel.com>
 44#    Jason Baron <jbaron@redhat.com>
 45#    Jason Gunthorpe <jgg@nvidia.com>
 46#    Jérémy Bobbio <lunar@debian.org>
 47#    Johannes Berg <johannes.berg@intel.com>
 48#    Johannes Weiner <hannes@cmpxchg.org>
 49#    Jonathan Cameron <Jonathan.Cameron@huawei.com>
 50#    Jonathan Corbet <corbet@lwn.net>
 51#    Jonathan Neuschäfer <j.neuschaefer@gmx.net>
 52#    Kamil Rytarowski <n54@gmx.com>
 53#    Kees Cook <kees@kernel.org>
 54#    Laurent Pinchart <laurent.pinchart@ideasonboard.com>
 55#    Levin, Alexander (Sasha Levin) <alexander.levin@verizon.com>
 56#    Linus Torvalds <torvalds@linux-foundation.org>
 57#    Lucas De Marchi <lucas.demarchi@profusion.mobi>
 58#    Mark Rutland <mark.rutland@arm.com>
 59#    Markus Heiser <markus.heiser@darmarit.de>
 60#    Martin Waitz <tali@admingilde.org>
 61#    Masahiro Yamada <masahiroy@kernel.org>
 62#    Matthew Wilcox <willy@infradead.org>
 63#    Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
 64#    Michal Wajdeczko <michal.wajdeczko@intel.com>
 65#    Michael Zucchi
 66#    Mike Rapoport <rppt@linux.ibm.com>
 67#    Niklas Söderlund <niklas.soderlund@corigine.com>
 68#    Nishanth Menon <nm@ti.com>
 69#    Paolo Bonzini <pbonzini@redhat.com>
 70#    Pavan Kumar Linga <pavan.kumar.linga@intel.com>
 71#    Pavel Pisa <pisa@cmp.felk.cvut.cz>
 72#    Peter Maydell <peter.maydell@linaro.org>
 73#    Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
 74#    Randy Dunlap <rdunlap@infradead.org>
 75#    Richard Kennedy <richard@rsk.demon.co.uk>
 76#    Rich Walker <rw@shadow.org.uk>
 77#    Rolf Eike Beer <eike-kernel@sf-tec.de>
 78#    Sakari Ailus <sakari.ailus@linux.intel.com>
 79#    Silvio Fricke <silvio.fricke@gmail.com>
 80#    Simon Huggins
 81#    Tim Waugh <twaugh@redhat.com>
 82#    Tomasz Warniełło <tomasz.warniello@gmail.com>
 83#    Utkarsh Tripathi <utripathi2002@gmail.com>
 84#    valdis.kletnieks@vt.edu <valdis.kletnieks@vt.edu>
 85#    Vegard Nossum <vegard.nossum@oracle.com>
 86#    Will Deacon <will.deacon@arm.com>
 87#    Yacine Belkadi <yacine.belkadi.1@gmail.com>
 88#    Yujie Liu <yujie.liu@intel.com>
 89
 90"""
 91kernel_doc
 92==========
 93
 94Print formatted kernel documentation to stdout
 95
 96Read C language source or header FILEs, extract embedded
 97documentation comments, and print formatted documentation
 98to standard output.
 99
100The documentation comments are identified by the "/**"
101opening comment mark.
102
103See Documentation/doc-guide/kernel-doc.rst for the
104documentation comment syntax.
105"""
106
107import argparse
108import logging
109import os
110import sys
111
112# Import Python modules
113
114LIB_DIR = "../tools/lib/python"
115SRC_DIR = os.path.dirname(os.path.realpath(__file__))
116
117sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
118
119WERROR_RETURN_CODE = 3
120
121DESC = """
122Read C language source or header FILEs, extract embedded documentation comments,
123and print formatted documentation to standard output.
124
125The documentation comments are identified by the "/**" opening comment mark.
126
127See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
128"""
129
130EXPORT_FILE_DESC = """
131Specify an additional FILE in which to look for EXPORT_SYMBOL information.
132
133May be used multiple times.
134"""
135
136EXPORT_DESC = """
137Only output documentation for the symbols that have been
138exported using EXPORT_SYMBOL() and related macros in any input
139FILE or -export-file FILE.
140"""
141
142INTERNAL_DESC = """
143Only output documentation for the symbols that have NOT been
144exported using EXPORT_SYMBOL() and related macros in any input
145FILE or -export-file FILE.
146"""
147
148FUNCTION_DESC = """
149Only output documentation for the given function or DOC: section
150title. All other functions and DOC: sections are ignored.
151
152May be used multiple times.
153"""
154
155NOSYMBOL_DESC = """
156Exclude the specified symbol from the output documentation.
157
158May be used multiple times.
159"""
160
161FILES_DESC = """
162Header and C source files to be parsed.
163"""
164
165WARN_CONTENTS_BEFORE_SECTIONS_DESC = """
166Warns if there are contents before sections (deprecated).
167
168This option is kept just for backward-compatibility, but it does nothing,
169neither here nor at the original Perl script.
170"""
171
172
173class MsgFormatter(logging.Formatter):
174    """Helper class to format warnings on a similar way to kernel-doc.pl"""
175
176    def format(self, record):
177        record.levelname = record.levelname.capitalize()
178        return logging.Formatter.format(self, record)
179
180def main():
181    """
182    Main program.
183
184    By default, the return value is:
185
186    - 0: success or Python version is not compatible with
187      kernel-doc.  If -Werror is not used, it will also
188      return 0 if there are issues at kernel-doc markups;
189
190    - 1: an abnormal condition happened;
191
192    - 2: argparse issued an error;
193
194    - 3: -Werror is used, and one or more unfiltered parse warnings happened.
195    """
196
197    parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
198                                     description=DESC)
199
200    # Normal arguments
201
202    parser.add_argument("-v", "-verbose", "--verbose", action="store_true",
203                        help="Verbose output, more warnings and other information.")
204
205    parser.add_argument("-d", "-debug", "--debug", action="store_true",
206                        help="Enable debug messages")
207
208    parser.add_argument("-M", "-modulename", "--modulename",
209                        default="Kernel API",
210                        help="Allow setting a module name at the output.")
211
212    parser.add_argument("-l", "-enable-lineno", "--enable_lineno",
213                        action="store_true",
214                        help="Enable line number output (only in ReST mode)")
215
216    # Arguments to control the warning behavior
217
218    parser.add_argument("-Wreturn", "--wreturn", action="store_true",
219                        help="Warns about the lack of a return markup on functions.")
220
221    parser.add_argument("-Wshort-desc", "-Wshort-description", "--wshort-desc",
222                        action="store_true",
223                        help="Warns if initial short description is missing")
224
225    parser.add_argument("-Wcontents-before-sections",
226                        "--wcontents-before-sections", action="store_true",
227                        help=WARN_CONTENTS_BEFORE_SECTIONS_DESC)
228
229    parser.add_argument("-Wall", "--wall", action="store_true",
230                        help="Enable all types of warnings")
231
232    parser.add_argument("-Werror", "--werror", action="store_true",
233                        help="Treat warnings as errors.")
234
235    parser.add_argument("-export-file", "--export-file", action='append',
236                        help=EXPORT_FILE_DESC)
237
238    # Output format mutually-exclusive group
239
240    out_group = parser.add_argument_group("Output format selection (mutually exclusive)")
241
242    out_fmt = out_group.add_mutually_exclusive_group()
243
244    out_fmt.add_argument("-m", "-man", "--man", action="store_true",
245                         help="Output troff manual page format.")
246    out_fmt.add_argument("-r", "-rst", "--rst", action="store_true",
247                         help="Output reStructuredText format (default).")
248    out_fmt.add_argument("-N", "-none", "--none", action="store_true",
249                         help="Do not output documentation, only warnings.")
250
251    # Output selection mutually-exclusive group
252
253    sel_group = parser.add_argument_group("Output selection (mutually exclusive)")
254    sel_mut = sel_group.add_mutually_exclusive_group()
255
256    sel_mut.add_argument("-e", "-export", "--export", action='store_true',
257                         help=EXPORT_DESC)
258
259    sel_mut.add_argument("-i", "-internal", "--internal", action='store_true',
260                         help=INTERNAL_DESC)
261
262    sel_mut.add_argument("-s", "-function", "--symbol", action='append',
263                         help=FUNCTION_DESC)
264
265    # Those are valid for all 3 types of filter
266    parser.add_argument("-n", "-nosymbol", "--nosymbol", action='append',
267                        help=NOSYMBOL_DESC)
268
269    parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections",
270                        action='store_true', help="Don't outputt DOC sections")
271
272    parser.add_argument("files", metavar="FILE",
273                        nargs="+", help=FILES_DESC)
274
275    args = parser.parse_args()
276
277    if args.wall:
278        args.wreturn = True
279        args.wshort_desc = True
280        args.wcontents_before_sections = True
281
282    logger = logging.getLogger()
283
284    if not args.debug:
285        logger.setLevel(logging.INFO)
286    else:
287        logger.setLevel(logging.DEBUG)
288
289    formatter = MsgFormatter('%(levelname)s: %(message)s')
290
291    handler = logging.StreamHandler()
292    handler.setFormatter(formatter)
293
294    logger.addHandler(handler)
295
296    python_ver = sys.version_info[:2]
297    if python_ver < (3,6):
298        # Depending on Kernel configuration, kernel-doc --none is called at
299        # build time. As we don't want to break compilation due to the
300        # usage of an old Python version, return 0 here.
301        if args.none:
302            logger.error("Python 3.6 or later is required by kernel-doc. skipping checks")
303            sys.exit(0)
304
305        sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.")
306
307    if python_ver < (3,7):
308        logger.warning("Python 3.7 or later is required for correct results")
309
310    # Import kernel-doc libraries only after checking Python version
311    from kdoc.kdoc_files import KernelFiles             # pylint: disable=C0415
312    from kdoc.kdoc_output import RestFormat, ManFormat  # pylint: disable=C0415
313
314    if args.man:
315        out_style = ManFormat(modulename=args.modulename)
316    elif args.none:
317        out_style = None
318    else:
319        out_style = RestFormat()
320
321    kfiles = KernelFiles(verbose=args.verbose,
322                         out_style=out_style, werror=args.werror,
323                         wreturn=args.wreturn, wshort_desc=args.wshort_desc,
324                         wcontents_before_sections=args.wcontents_before_sections)
325
326    kfiles.parse(args.files, export_file=args.export_file)
327
328    for t in kfiles.msg(enable_lineno=args.enable_lineno, export=args.export,
329                        internal=args.internal, symbol=args.symbol,
330                        nosymbol=args.nosymbol, export_file=args.export_file,
331                        no_doc_sections=args.no_doc_sections):
332        msg = t[1]
333        if msg:
334            print(msg)
335
336    error_count = kfiles.errors
337    if not error_count:
338        sys.exit(0)
339
340    if args.werror:
341        print("%s warnings as errors" % error_count)    # pylint: disable=C0209
342        sys.exit(WERROR_RETURN_CODE)
343
344    if args.verbose:
345        print("%s errors" % error_count)                # pylint: disable=C0209
346
347    sys.exit(0)
348
349# Call main method
350if __name__ == "__main__":
351    main()