[PATCH v3 05/33] scripts/kernel-doc.py: better handle empty sections

Mauro Carvalho Chehab
2025-04-08T10:09:56Z

While doing the conversion, we opted to skip empty sections
(description, return), but this makes harder to see the differences
between kernel-doc (Perl) and kernel-doc.py.

Also, the logic doesn't always work properly. So, change the
way this is done by adding an extra step to remove such
sections, doing it only for Return and Description.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/kernel-doc.py | 31 ++++++++++++++++++++++++++++---
1 file changed, 28 insertions(+), 3 deletions(-)

diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index 8625209d6293..90808d538de7 100755
--- a/scripts/kernel-doc.py
+++ b/scripts/kernel-doc.py
@@ -317,6 +317,19 @@ class KernelDoc:
name = self.entry.section
contents = self.entry.contents

+ # TODO: we can prevent dumping empty sections here with:
+ #
+ # if self.entry.contents.strip("\n"):
+ # if start_new:
+ # self.entry.section = self.section_default
+ # self.entry.contents = ""
+ #
+ # return
+ #
+ # But, as we want to be producing the same output of the
+ # venerable kernel-doc Perl tool, let's just output everything,
+ # at least for now
+
if type_param.match(name):
name = type_param.group(1)

@@ -373,6 +386,19 @@ class KernelDoc:

args["type"] = dtype

+ # TODO: use colletions.OrderedDict
+
+ sections = args.get('sections', {})
+ sectionlist = args.get('sectionlist', [])
+
+ # Drop empty sections
+ # TODO: improve it to emit warnings
+ for section in [ "Description", "Return" ]:
+ if section in sectionlist:
+ if not sections[section].rstrip():
+ del sections[section]
+ sectionlist.remove(section)
+
self.entries.append((name, args))

self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
@@ -476,7 +502,7 @@ class KernelDoc:
# to ignore "[blah" in a parameter string.

self.entry.parameterlist.append(param)
- org_arg = Re(r'\s\s+').sub(' ', org_arg, count=1)
+ org_arg = Re(r'\s\s+').sub(' ', org_arg)
self.entry.parametertypes[param] = org_arg

def save_struct_actual(self, actual):
@@ -1384,8 +1410,7 @@ class KernelDoc:
return

if doc_end.search(line):
- if self.entry.contents.strip("\n"):
- self.dump_section()
+ self.dump_section()

# Look for doc_com + <text> + doc_end:
r = Re(r'\s*\*\s*[a-zA-Z_0-9:\.]+\*/')
--
2.49.0