public-mirrors/linux
1
0
Fork 0
mirror of git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2025-09-18 22:14:16 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: kdoc: pretty up dump_enum()

Browse source 
Add some comments to dump_enum to help the next person who has to figure
out what it is actually doing.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250703184403.274408-8-corbet@lwn.net
This commit is contained in:
Jonathan Corbet 2025-07-03 12:44:03 -06:00
parent 92fb8091c0
commit 5d77dcc07f
1 changed files with 25 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
scripts/lib/kdoc/kdoc_parser.py
View file

@ -860,39 +860,48 @@ class KernelDoc:
# Strip #define macros inside enums
proto = KernRe(r'#\s*((define|ifdef|if)\s+|endif)[^;]*;', flags=re.S).sub('', proto)
members = None
declaration_name = None
#
# Parse out the name and members of the enum. Typedef form first.
#
r = KernRe(r'typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;')
if r.search(proto):
declaration_name = r.group(2)
members = r.group(1).rstrip()
#
# Failing that, look for a straight enum
#
else:
r = KernRe(r'enum\s+(\w*)\s*\{(.*)\}')
if r.match(proto):
declaration_name = r.group(1)
members = r.group(2).rstrip()
if not members:
self.emit_msg(ln, f"{proto}: error: Cannot parse enum!")
return
#
# OK, this isn't going to work.
#
else:
self.emit_msg(ln, f"{proto}: error: Cannot parse enum!")
return
#
# Make sure we found what we were expecting.
#
if self.entry.identifier != declaration_name:
if self.entry.identifier == "":
self.emit_msg(ln,
f"{proto}: wrong kernel-doc identifier on prototype")
else:
self.emit_msg(ln,
f"expecting prototype for enum {self.entry.identifier}. Prototype was for enum {declaration_name} instead")
f"expecting prototype for enum {self.entry.identifier}. "
f"Prototype was for enum {declaration_name} instead")
return
if not declaration_name:
declaration_name = "(anonymous)"
#
# Parse out the name of each enum member, and verify that we
# have a description for it.
#
member_set = set()
members = KernRe(r'\([^;]*?[\)]').sub('', members)
members = KernRe(r'\([^;)]*\)').sub('', members)
for arg in members.split(','):
if not arg:
continue
@ -903,7 +912,9 @@ class KernelDoc:
self.emit_msg(ln,
f"Enum value '{arg}' not described in enum '{declaration_name}'")
member_set.add(arg)
#
# Ensure that every described member actually exists in the enum.
#
for k in self.entry.parameterdescs:
if k not in member_set:
self.emit_msg(ln,