Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kdoc; Add a rudimentary class to represent output items
This class is intended to replace the unstructured dict used to accumulate
an entry to pass to an output module. For now, it remains unstructured,
but it works well enough that the output classes don't notice the
difference.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
+35
-21
+26
scripts/lib/kdoc/kdoc_item.py
+26
scripts/lib/kdoc/kdoc_item.py
···
1
+
# SPDX-License-Identifier: GPL-2.0
2
+
#
3
+
# A class that will, eventually, encapsulate all of the parsed data that we
4
+
# then pass into the output modules.
5
+
#
6
+
7
+
class KdocItem:
8
+
def __init__(self, name, type, start_line, **other_stuff):
9
+
self.name = name
10
+
self.type = type
11
+
self.declaration_start_line = start_line
12
+
#
13
+
# Just save everything else into our own dict so that the output
14
+
# side can grab it directly as before. As we move things into more
15
+
# structured data, this will, hopefully, fade away.
16
+
#
17
+
self.other_stuff = other_stuff
18
+
19
+
def get(self, key, default = None):
20
+
ret = self.other_stuff.get(key, default)
21
+
if ret == default:
22
+
return self.__dict__.get(key, default)
23
+
return ret
24
+
25
+
def __getitem__(self, key):
26
+
return self.get(key)
+9
-21
scripts/lib/kdoc/kdoc_parser.py
+9
-21
scripts/lib/kdoc/kdoc_parser.py
···
16
16
from pprint import pformat
17
17
18
18
from kdoc_re import NestedMatch, KernRe
19
-
19
+
from kdoc_item import KdocItem
20
20
21
21
#
22
22
# Regular expressions used to parse kernel-doc markups at KernelDoc class.
···
271
271
The actual output and output filters will be handled elsewhere
272
272
"""
273
273
274
-
# The implementation here is different than the original kernel-doc:
275
-
# instead of checking for output filters or actually output anything,
276
-
# it just stores the declaration content at self.entries, as the
277
-
# output will happen on a separate class.
278
-
#
279
-
# For now, we're keeping the same name of the function just to make
280
-
# easier to compare the source code of both scripts
274
+
item = KdocItem(name, dtype, self.entry.declaration_start_line, **args)
275
+
item.warnings = self.entry.warnings
281
276
282
-
args["declaration_start_line"] = self.entry.declaration_start_line
283
-
args["type"] = dtype
284
-
args["warnings"] = self.entry.warnings
285
-
286
-
# TODO: use colletions.OrderedDict to remove sectionlist
287
-
288
-
sections = args.get('sections', {})
289
-
sectionlist = args.get('sectionlist', [])
277
+
sections = item.get('sections', {})
278
+
sectionlist = item.get('sectionlist', [])
290
279
291
280
# Drop empty sections
292
281
# TODO: improve empty sections logic to emit warnings
293
282
for section in ["Description", "Return"]:
294
-
if section in sectionlist:
295
-
if not sections[section].rstrip():
296
-
del sections[section]
297
-
sectionlist.remove(section)
283
+
if section in sectionlist and not sections[section].rstrip():
284
+
del sections[section]
285
+
sectionlist.remove(section)
298
286
299
-
self.entries.append((name, args))
287
+
self.entries.append((name, item))
300
288
301
289
self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
302
290