tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

docs: kdoc_files: document KernelFiles() ABI

The KernelFiles is the main entry point to run kernel-doc,
being used by both tools/docs/kernel-doc and
Documentation/sphinx/kerneldoc.py.

It is also used on QEMU, which also uses the kernel-doc
libraries from tools/lib/python/kdoc.

Properly describe its ABI contract.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <13eb44c341232564eaf2a9c9de4782369fef57e1.1772810574.git.mchehab+huawei@kernel.org>

authored by

Mauro Carvalho Chehab and committed by
Jonathan Corbet 0d3ab0e4 861dcdb6

+43 -1
+43 -1
tools/lib/python/kdoc/kdoc_files.py
··· 91 91 """ 92 92 Parse kernel-doc tags on multiple kernel source files. 93 93 94 - There are two type of parsers defined here: 94 + This is the main entry point to run kernel-doc. This class is initialized 95 + using a series of optional arguments: 96 + 97 + ``verbose`` 98 + If True, enables kernel-doc verbosity. Default: False. 99 + 100 + ``out_style`` 101 + Class to be used to format output. If None (default), 102 + only report errors. 103 + 104 + ``xforms`` 105 + Transforms to be applied to C prototypes and data structs. 106 + If not specified, defaults to xforms = CFunction() 107 + 108 + ``werror`` 109 + If True, treat warnings as errors, retuning an error code on warnings. 110 + 111 + Default: False. 112 + 113 + ``wreturn`` 114 + If True, warns about the lack of a return markup on functions. 115 + 116 + Default: False. 117 + ``wshort_desc`` 118 + If True, warns if initial short description is missing. 119 + 120 + Default: False. 121 + 122 + ``wcontents_before_sections`` 123 + If True, warn if there are contents before sections (deprecated). 124 + This option is kept just for backward-compatibility, but it does 125 + nothing, neither here nor at the original Perl script. 126 + 127 + Default: False. 128 + 129 + ``logger`` 130 + Optional logger class instance. 131 + 132 + If not specified, defaults to use: ``logging.getLogger("kernel-doc")`` 133 + 134 + Note: 135 + There are two type of parsers defined here: 136 + 95 137 - self.parse_file(): parses both kernel-doc markups and 96 138 ``EXPORT_SYMBOL*`` macros; 97 139 - self.process_export_file(): parses only ``EXPORT_SYMBOL*`` macros.