projects/linux·blob v6.19-rc4 · refs

339 lines · 11.8 KiB

1#!/usr/bin/env python3
2# SPDX-License-Identifier: GPL-2.0
3# Copyright(c) 2025: Mauro Carvalho Chehab <[email protected]>.
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 <[email protected]>
20# Akira Yokosawa <[email protected]>
21# Alexander A. Klimov <[email protected]>
22# Alexander Lobakin <[email protected]>
23# André Almeida <[email protected]>
24# Andy Shevchenko <[email protected]>
25# Anna-Maria Behnsen <[email protected]>
26# Armin Kuster <[email protected]>
27# Bart Van Assche <[email protected]>
28# Ben Hutchings <[email protected]>
29# Borislav Petkov <[email protected]>
30# Chen-Yu Tsai <[email protected]>
31# Coco Li <[email protected]>
32# Conchúr Navid <[email protected]>
33# Daniel Santos <[email protected]>
34# Danilo Cesar Lemes de Paula <[email protected]>
35# Dan Luedtke <[email protected]>
36# Donald Hunter <[email protected]>
37# Gabriel Krisman Bertazi <[email protected]>
38# Greg Kroah-Hartman <[email protected]>
39# Harvey Harrison <[email protected]>
40# Horia Geanta <[email protected]>
41# Ilya Dryomov <[email protected]>
42# Jakub Kicinski <[email protected]>
43# Jani Nikula <[email protected]>
44# Jason Baron <[email protected]>
45# Jason Gunthorpe <[email protected]>
46# Jérémy Bobbio <[email protected]>
47# Johannes Berg <[email protected]>
48# Johannes Weiner <[email protected]>
49# Jonathan Cameron <[email protected]>
50# Jonathan Corbet <[email protected]>
51# Jonathan Neuschäfer <[email protected]>
52# Kamil Rytarowski <[email protected]>
53# Kees Cook <[email protected]>
54# Laurent Pinchart <[email protected]>
55# Levin, Alexander (Sasha Levin) <[email protected]>
56# Linus Torvalds <[email protected]>
57# Lucas De Marchi <[email protected]>
58# Mark Rutland <[email protected]>
59# Markus Heiser <[email protected]>
60# Martin Waitz <[email protected]>
61# Masahiro Yamada <[email protected]>
62# Matthew Wilcox <[email protected]>
63# Mauro Carvalho Chehab <[email protected]>
64# Michal Wajdeczko <[email protected]>
65# Michael Zucchi
66# Mike Rapoport <[email protected]>
67# Niklas Söderlund <[email protected]>
68# Nishanth Menon <[email protected]>
69# Paolo Bonzini <[email protected]>
70# Pavan Kumar Linga <[email protected]>
71# Pavel Pisa <[email protected]>
72# Peter Maydell <[email protected]>
73# Pierre-Louis Bossart <[email protected]>
74# Randy Dunlap <[email protected]>
75# Richard Kennedy <[email protected]>
76# Rich Walker <[email protected]>
77# Rolf Eike Beer <[email protected]>
78# Sakari Ailus <[email protected]>
79# Silvio Fricke <[email protected]>
80# Simon Huggins
81# Tim Waugh <[email protected]>
82# Tomasz Warniełło <[email protected]>
83# Utkarsh Tripathi <[email protected]>
84# [email protected] <[email protected]>
85# Vegard Nossum <[email protected]>
86# Will Deacon <[email protected]>
87# Yacine Belkadi <[email protected]>
88# Yujie Liu <[email protected]>
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
119DESC = """
120Read C language source or header FILEs, extract embedded documentation comments,
121and print formatted documentation to standard output.
122
123The documentation comments are identified by the "/**" opening comment mark.
124
125See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
126"""
127
128EXPORT_FILE_DESC = """
129Specify an additional FILE in which to look for EXPORT_SYMBOL information.
130
131May be used multiple times.
132"""
133
134EXPORT_DESC = """
135Only output documentation for the symbols that have been
136exported using EXPORT_SYMBOL() and related macros in any input
137FILE or -export-file FILE.
138"""
139
140INTERNAL_DESC = """
141Only output documentation for the symbols that have NOT been
142exported using EXPORT_SYMBOL() and related macros in any input
143FILE or -export-file FILE.
144"""
145
146FUNCTION_DESC = """
147Only output documentation for the given function or DOC: section
148title. All other functions and DOC: sections are ignored.
149
150May be used multiple times.
151"""
152
153NOSYMBOL_DESC = """
154Exclude the specified symbol from the output documentation.
155
156May be used multiple times.
157"""
158
159FILES_DESC = """
160Header and C source files to be parsed.
161"""
162
163WARN_CONTENTS_BEFORE_SECTIONS_DESC = """
164Warns if there are contents before sections (deprecated).
165
166This option is kept just for backward-compatibility, but it does nothing,
167neither here nor at the original Perl script.
168"""
169
170
171class MsgFormatter(logging.Formatter):
172 """Helper class to format warnings on a similar way to kernel-doc.pl"""
173
174 def format(self, record):
175 record.levelname = record.levelname.capitalize()
176 return logging.Formatter.format(self, record)
177
178def main():
179 """Main program"""
180
181 parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
182 description=DESC)
183
184 # Normal arguments
185
186 parser.add_argument("-v", "-verbose", "--verbose", action="store_true",
187 help="Verbose output, more warnings and other information.")
188
189 parser.add_argument("-d", "-debug", "--debug", action="store_true",
190 help="Enable debug messages")
191
192 parser.add_argument("-M", "-modulename", "--modulename",
193 default="Kernel API",
194 help="Allow setting a module name at the output.")
195
196 parser.add_argument("-l", "-enable-lineno", "--enable_lineno",
197 action="store_true",
198 help="Enable line number output (only in ReST mode)")
199
200 # Arguments to control the warning behavior
201
202 parser.add_argument("-Wreturn", "--wreturn", action="store_true",
203 help="Warns about the lack of a return markup on functions.")
204
205 parser.add_argument("-Wshort-desc", "-Wshort-description", "--wshort-desc",
206 action="store_true",
207 help="Warns if initial short description is missing")
208
209 parser.add_argument("-Wcontents-before-sections",
210 "--wcontents-before-sections", action="store_true",
211 help=WARN_CONTENTS_BEFORE_SECTIONS_DESC)
212
213 parser.add_argument("-Wall", "--wall", action="store_true",
214 help="Enable all types of warnings")
215
216 parser.add_argument("-Werror", "--werror", action="store_true",
217 help="Treat warnings as errors.")
218
219 parser.add_argument("-export-file", "--export-file", action='append',
220 help=EXPORT_FILE_DESC)
221
222 # Output format mutually-exclusive group
223
224 out_group = parser.add_argument_group("Output format selection (mutually exclusive)")
225
226 out_fmt = out_group.add_mutually_exclusive_group()
227
228 out_fmt.add_argument("-m", "-man", "--man", action="store_true",
229 help="Output troff manual page format.")
230 out_fmt.add_argument("-r", "-rst", "--rst", action="store_true",
231 help="Output reStructuredText format (default).")
232 out_fmt.add_argument("-N", "-none", "--none", action="store_true",
233 help="Do not output documentation, only warnings.")
234
235 # Output selection mutually-exclusive group
236
237 sel_group = parser.add_argument_group("Output selection (mutually exclusive)")
238 sel_mut = sel_group.add_mutually_exclusive_group()
239
240 sel_mut.add_argument("-e", "-export", "--export", action='store_true',
241 help=EXPORT_DESC)
242
243 sel_mut.add_argument("-i", "-internal", "--internal", action='store_true',
244 help=INTERNAL_DESC)
245
246 sel_mut.add_argument("-s", "-function", "--symbol", action='append',
247 help=FUNCTION_DESC)
248
249 # Those are valid for all 3 types of filter
250 parser.add_argument("-n", "-nosymbol", "--nosymbol", action='append',
251 help=NOSYMBOL_DESC)
252
253 parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections",
254 action='store_true', help="Don't outputt DOC sections")
255
256 parser.add_argument("files", metavar="FILE",
257 nargs="+", help=FILES_DESC)
258
259 args = parser.parse_args()
260
261 if args.wall:
262 args.wreturn = True
263 args.wshort_desc = True
264 args.wcontents_before_sections = True
265
266 logger = logging.getLogger()
267
268 if not args.debug:
269 logger.setLevel(logging.INFO)
270 else:
271 logger.setLevel(logging.DEBUG)
272
273 formatter = MsgFormatter('%(levelname)s: %(message)s')
274
275 handler = logging.StreamHandler()
276 handler.setFormatter(formatter)
277
278 logger.addHandler(handler)
279
280 python_ver = sys.version_info[:2]
281 if python_ver < (3,6):
282 # Depending on Kernel configuration, kernel-doc --none is called at
283 # build time. As we don't want to break compilation due to the
284 # usage of an old Python version, return 0 here.
285 if args.none:
286 logger.error("Python 3.6 or later is required by kernel-doc. skipping checks")
287 sys.exit(0)
288
289 sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.")
290
291 if python_ver < (3,7):
292 logger.warning("Python 3.7 or later is required for correct results")
293
294 # Import kernel-doc libraries only after checking Python version
295 from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415
296 from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415
297
298 if args.man:
299 out_style = ManFormat(modulename=args.modulename)
300 elif args.none:
301 out_style = None
302 else:
303 out_style = RestFormat()
304
305 kfiles = KernelFiles(verbose=args.verbose,
306 out_style=out_style, werror=args.werror,
307 wreturn=args.wreturn, wshort_desc=args.wshort_desc,
308 wcontents_before_sections=args.wcontents_before_sections)
309
310 kfiles.parse(args.files, export_file=args.export_file)
311
312 for t in kfiles.msg(enable_lineno=args.enable_lineno, export=args.export,
313 internal=args.internal, symbol=args.symbol,
314 nosymbol=args.nosymbol, export_file=args.export_file,
315 no_doc_sections=args.no_doc_sections):
316 msg = t[1]
317 if msg:
318 print(msg)
319
320 error_count = kfiles.errors
321 if not error_count:
322 sys.exit(0)
323
324 if args.werror:
325 print("%s warnings as errors" % error_count) # pylint: disable=C0209
326 sys.exit(error_count)
327
328 if args.verbose:
329 print("%s errors" % error_count) # pylint: disable=C0209
330
331 if args.none:
332 sys.exit(0)
333
334 sys.exit(error_count)
335
336
337# Call main method
338if __name__ == "__main__":
339 main()