Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kdoc: pretty up dump_enum()
Add some comments to dump_enum to help the next person who has to figure
out what it is actually doing.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
+25
-14
+25
-14
scripts/lib/kdoc/kdoc_parser.py
+25
-14
scripts/lib/kdoc/kdoc_parser.py
···
860
860
# Strip #define macros inside enums
861
861
proto = KernRe(r'#\s*((define|ifdef|if)\s+|endif)[^;]*;', flags=re.S).sub('', proto)
862
862
863
-
members = None
864
-
declaration_name = None
865
-
863
+
#
864
+
# Parse out the name and members of the enum. Typedef form first.
865
+
#
866
866
r = KernRe(r'typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;')
867
867
if r.search(proto):
868
868
declaration_name = r.group(2)
869
869
members = r.group(1).rstrip()
870
+
#
871
+
# Failing that, look for a straight enum
872
+
#
870
873
else:
871
874
r = KernRe(r'enum\s+(\w*)\s*\{(.*)\}')
872
875
if r.match(proto):
873
876
declaration_name = r.group(1)
874
877
members = r.group(2).rstrip()
875
-
876
-
if not members:
877
-
self.emit_msg(ln, f"{proto}: error: Cannot parse enum!")
878
-
return
879
-
878
+
#
879
+
# OK, this isn't going to work.
880
+
#
881
+
else:
882
+
self.emit_msg(ln, f"{proto}: error: Cannot parse enum!")
883
+
return
884
+
#
885
+
# Make sure we found what we were expecting.
886
+
#
880
887
if self.entry.identifier != declaration_name:
881
888
if self.entry.identifier == "":
882
889
self.emit_msg(ln,
883
890
f"{proto}: wrong kernel-doc identifier on prototype")
884
891
else:
885
892
self.emit_msg(ln,
886
-
f"expecting prototype for enum {self.entry.identifier}. Prototype was for enum {declaration_name} instead")
893
+
f"expecting prototype for enum {self.entry.identifier}. "
894
+
f"Prototype was for enum {declaration_name} instead")
887
895
return
888
896
889
897
if not declaration_name:
890
898
declaration_name = "(anonymous)"
891
-
899
+
#
900
+
# Parse out the name of each enum member, and verify that we
901
+
# have a description for it.
902
+
#
892
903
member_set = set()
893
-
894
-
members = KernRe(r'\([^;]*?[\)]').sub('', members)
895
-
904
+
members = KernRe(r'\([^;)]*\)').sub('', members)
896
905
for arg in members.split(','):
897
906
if not arg:
898
907
continue
···
912
903
self.emit_msg(ln,
913
904
f"Enum value '{arg}' not described in enum '{declaration_name}'")
914
905
member_set.add(arg)
915
-
906
+
#
907
+
# Ensure that every described member actually exists in the enum.
908
+
#
916
909
for k in self.entry.parameterdescs:
917
910
if k not in member_set:
918
911
self.emit_msg(ln,