Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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# - f-strings cannot be used in this file.
13# - libraries that require newer versions can only be included
14# after the Python version has been 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"""
91Print formatted kernel documentation to stdout.
92
93Read C language source or header FILEs, extract embedded
94documentation comments, and print formatted documentation
95to standard output.
96
97The documentation comments are identified by the ``/**``
98opening comment mark.
99
100See Documentation/doc-guide/kernel-doc.rst for the
101documentation comment syntax.
102"""
103
104import argparse
105import logging
106import os
107import sys
108
109# Import Python modules
110
111LIB_DIR = "../lib/python"
112SRC_DIR = os.path.dirname(os.path.realpath(__file__))
113
114sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
115
116WERROR_RETURN_CODE = 3
117
118DESC = """
119Read C language source or header FILEs, extract embedded documentation comments,
120and print formatted documentation to standard output.
121
122The documentation comments are identified by the "/**" opening comment mark.
123
124See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
125"""
126
127EXPORT_FILE_DESC = """
128Specify an additional FILE in which to look for EXPORT_SYMBOL information.
129
130May be used multiple times.
131"""
132
133EXPORT_DESC = """
134Only output documentation for symbols that have been
135exported using EXPORT_SYMBOL() and related macros in any input
136FILE or -export-file FILE.
137"""
138
139INTERNAL_DESC = """
140Only output documentation for symbols that have NOT been
141exported using EXPORT_SYMBOL() and related macros in any input
142FILE or -export-file FILE.
143"""
144
145FUNCTION_DESC = """
146Only output documentation for the given function or DOC: section
147title. All other functions and DOC: sections are ignored.
148
149May be used multiple times.
150"""
151
152NOSYMBOL_DESC = """
153Exclude the specified symbol from the output documentation.
154
155May be used multiple times.
156"""
157
158FILES_DESC = """
159Header and C source files to be parsed.
160"""
161
162WARN_CONTENTS_BEFORE_SECTIONS_DESC = """
163Warn if there are contents before sections (deprecated).
164
165This option is kept just for backward-compatibility, but it does nothing,
166neither here nor at the original Perl script.
167"""
168
169EPILOG = """
170The return value is:
171
172- 0: success or Python version is not compatible with
173kernel-doc. If -Werror is not used, it will also
174return 0 if there are issues at kernel-doc markups;
175
176- 1: an abnormal condition happened;
177
178- 2: argparse issued an error;
179
180- 3: When -Werror is used, it means that one or more unfiltered parse
181 warnings happened.
182"""
183
184class MsgFormatter(logging.Formatter):
185 """
186 Helper class to capitalize errors and warnings, the same way
187 the venerable (now retired) kernel-doc.pl used to do.
188 """
189
190 def format(self, record):
191 record.levelname = record.levelname.capitalize()
192 return logging.Formatter.format(self, record)
193
194def main():
195 """
196 Main program.
197
198 """
199
200 parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
201 description=DESC, epilog=EPILOG)
202
203 #
204 # Normal arguments
205 #
206 parser.add_argument("-v", "-verbose", "--verbose", action="store_true",
207 help="Verbose output, more warnings and other information.")
208
209 parser.add_argument("-d", "-debug", "--debug", action="store_true",
210 help="Enable debug messages")
211
212 parser.add_argument("-M", "-modulename", "--modulename",
213 default="Kernel API",
214 help="Allow setting a module name at the output.")
215
216 parser.add_argument("-l", "-enable-lineno", "--enable_lineno",
217 action="store_true",
218 help="Enable line number output (only in ReST mode)")
219
220 #
221 # Arguments to control the warning behavior
222 #
223 parser.add_argument("-Wreturn", "--wreturn", action="store_true",
224 help="Warns about the lack of a return markup on functions.")
225
226 parser.add_argument("-Wshort-desc", "-Wshort-description", "--wshort-desc",
227 action="store_true",
228 help="Warns if initial short description is missing")
229
230 parser.add_argument("-Wcontents-before-sections",
231 "--wcontents-before-sections", action="store_true",
232 help=WARN_CONTENTS_BEFORE_SECTIONS_DESC)
233
234 parser.add_argument("-Wall", "--wall", action="store_true",
235 help="Enable all types of warnings")
236
237 parser.add_argument("-Werror", "--werror", action="store_true",
238 help="Treat warnings as errors.")
239
240 parser.add_argument("-export-file", "--export-file", action='append',
241 help=EXPORT_FILE_DESC)
242
243 #
244 # Output format mutually-exclusive group
245 #
246 out_group = parser.add_argument_group("Output format selection (mutually exclusive)")
247
248 out_fmt = out_group.add_mutually_exclusive_group()
249
250 out_fmt.add_argument("-m", "-man", "--man", action="store_true",
251 help="Output troff manual page format.")
252 out_fmt.add_argument("-r", "-rst", "--rst", action="store_true",
253 help="Output reStructuredText format (default).")
254 out_fmt.add_argument("-N", "-none", "--none", action="store_true",
255 help="Do not output documentation, only warnings.")
256
257 #
258 # Output selection mutually-exclusive group
259 #
260 sel_group = parser.add_argument_group("Output selection (mutually exclusive)")
261 sel_mut = sel_group.add_mutually_exclusive_group()
262
263 sel_mut.add_argument("-e", "-export", "--export", action='store_true',
264 help=EXPORT_DESC)
265
266 sel_mut.add_argument("-i", "-internal", "--internal", action='store_true',
267 help=INTERNAL_DESC)
268
269 sel_mut.add_argument("-s", "-function", "--symbol", action='append',
270 help=FUNCTION_DESC)
271
272 #
273 # Those are valid for all 3 types of filter
274 #
275 parser.add_argument("-n", "-nosymbol", "--nosymbol", action='append',
276 help=NOSYMBOL_DESC)
277
278 parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections",
279 action='store_true', help="Don't output DOC sections")
280
281 parser.add_argument("files", metavar="FILE",
282 nargs="+", help=FILES_DESC)
283
284 args = parser.parse_args()
285
286 if args.wall:
287 args.wreturn = True
288 args.wshort_desc = True
289 args.wcontents_before_sections = True
290
291 logger = logging.getLogger()
292
293 if not args.debug:
294 logger.setLevel(logging.INFO)
295 else:
296 logger.setLevel(logging.DEBUG)
297
298 formatter = MsgFormatter('%(levelname)s: %(message)s')
299
300 handler = logging.StreamHandler()
301 handler.setFormatter(formatter)
302
303 logger.addHandler(handler)
304
305 python_ver = sys.version_info[:2]
306 if python_ver < (3,6):
307 #
308 # Depending on the Kernel configuration, kernel-doc --none is called at
309 # build time. As we don't want to break compilation due to the
310 # usage of an old Python version, return 0 here.
311 #
312 if args.none:
313 logger.error("Python 3.6 or later is required by kernel-doc. Skipping checks")
314 sys.exit(0)
315
316 sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.")
317
318 if python_ver < (3,7):
319 logger.warning("Python 3.7 or later is required for correct results")
320
321 #
322 # Import kernel-doc libraries only after checking the Python version
323 #
324 from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415
325 from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415
326
327 if args.man:
328 out_style = ManFormat(modulename=args.modulename)
329 elif args.none:
330 out_style = None
331 else:
332 out_style = RestFormat()
333
334 kfiles = KernelFiles(verbose=args.verbose,
335 out_style=out_style, werror=args.werror,
336 wreturn=args.wreturn, wshort_desc=args.wshort_desc,
337 wcontents_before_sections=args.wcontents_before_sections)
338
339 kfiles.parse(args.files, export_file=args.export_file)
340
341 for t in kfiles.msg(enable_lineno=args.enable_lineno, export=args.export,
342 internal=args.internal, symbol=args.symbol,
343 nosymbol=args.nosymbol, export_file=args.export_file,
344 no_doc_sections=args.no_doc_sections):
345 msg = t[1]
346 if msg:
347 print(msg)
348
349 error_count = kfiles.errors
350 if not error_count:
351 sys.exit(0)
352
353 if args.werror:
354 print("%s warnings as errors" % error_count) # pylint: disable=C0209
355 sys.exit(WERROR_RETURN_CODE)
356
357 if args.verbose:
358 print("%s errors" % error_count) # pylint: disable=C0209
359
360 sys.exit(0)
361
362#
363# Call main method
364#
365if __name__ == "__main__":
366 main()