Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kdoc_files: Improve docstrings and comments
In preparation to document kernel-doc module, improve its
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <75d58878ad6f83f24f1c0ce9e04301a000ecbaa3.1768838938.git.mchehab+huawei@kernel.org>
authored by
Mauro Carvalho Chehab
and committed by
Jonathan Corbet
8d08c7c6
4d7f6319
+12
-11
+12
-11
tools/lib/python/kdoc/kdoc_files.py
+12
-11
tools/lib/python/kdoc/kdoc_files.py
···
5
5
# pylint: disable=R0903,R0913,R0914,R0917
6
6
7
7
"""
8
-
Parse lernel-doc tags on multiple kernel source files.
8
+
Classes for navigating through the files that kernel-doc needs to handle
9
+
to generate documentation.
9
10
"""
10
11
11
12
import argparse
···
44
43
self.srctree = srctree
45
44
46
45
def _parse_dir(self, dirname):
47
-
"""Internal function to parse files recursively"""
46
+
"""Internal function to parse files recursively."""
48
47
49
48
with os.scandir(dirname) as obj:
50
49
for entry in obj:
···
66
65
def parse_files(self, file_list, file_not_found_cb):
67
66
"""
68
67
Define an iterator to parse all source files from file_list,
69
-
handling directories if any
68
+
handling directories if any.
70
69
"""
71
70
72
71
if not file_list:
···
92
91
93
92
There are two type of parsers defined here:
94
93
- self.parse_file(): parses both kernel-doc markups and
95
-
EXPORT_SYMBOL* macros;
96
-
- self.process_export_file(): parses only EXPORT_SYMBOL* macros.
94
+
``EXPORT_SYMBOL*`` macros;
95
+
- self.process_export_file(): parses only ``EXPORT_SYMBOL*`` macros.
97
96
"""
98
97
99
98
def warning(self, msg):
100
-
"""Ancillary routine to output a warning and increment error count"""
99
+
"""Ancillary routine to output a warning and increment error count."""
101
100
102
101
self.config.log.warning(msg)
103
102
self.errors += 1
104
103
105
104
def error(self, msg):
106
-
"""Ancillary routine to output an error and increment error count"""
105
+
"""Ancillary routine to output an error and increment error count."""
107
106
108
107
self.config.log.error(msg)
109
108
self.errors += 1
···
129
128
130
129
def process_export_file(self, fname):
131
130
"""
132
-
Parses EXPORT_SYMBOL* macros from a single Kernel source file.
131
+
Parses ``EXPORT_SYMBOL*`` macros from a single Kernel source file.
133
132
"""
134
133
135
134
# Prevent parsing the same file twice if results are cached
···
158
157
wcontents_before_sections=False,
159
158
logger=None):
160
159
"""
161
-
Initialize startup variables and parse all files
160
+
Initialize startup variables and parse all files.
162
161
"""
163
162
164
163
if not verbose:
···
214
213
215
214
def parse(self, file_list, export_file=None):
216
215
"""
217
-
Parse all files
216
+
Parse all files.
218
217
"""
219
218
220
219
glob = GlobSourceFiles(srctree=self.config.src_tree)
···
243
242
filenames=None, export_file=None):
244
243
"""
245
244
Interacts over the kernel-doc results and output messages,
246
-
returning kernel-doc markups on each interaction
245
+
returning kernel-doc markups on each interaction.
247
246
"""
248
247
249
248
self.out_style.set_config(self.config)