[PATCH v3 15/33] scripts/kernel-doc.py: fix handling of doc output check

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

The filtering logic was seeking for the DOC name to check for
symbols, but such data is stored only inside a section. Add it
to the output_declaration, as it is quicker/easier to check
the declaration name than to check inside each section.

While here, make sure that the output for both ReST and man
after filtering will be similar to what kernel-doc Perl
version does.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/lib/kdoc/kdoc_output.py | 29 ++++++++++++-----------------
scripts/lib/kdoc/kdoc_parser.py | 3 ++-
2 files changed, 14 insertions(+), 18 deletions(-)

diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output.py
index 6a7187980bec..7a945dd80c9b 100755
--- a/scripts/lib/kdoc/kdoc_output.py
+++ b/scripts/lib/kdoc/kdoc_output.py
@@ -122,13 +122,13 @@ class OutputFormat:
if self.no_doc_sections:
return False

+ if name in self.nosymbol:
+ return False
+
if self.out_mode == self.OUTPUT_ALL:
return True

if self.out_mode == self.OUTPUT_INCLUDE:
- if name in self.nosymbol:
- return False
-
if name in self.function_table:
return True

@@ -154,15 +154,6 @@ class OutputFormat:

return False

- def check_function(self, fname, name, args):
- return True
-
- def check_enum(self, fname, name, args):
- return True
-
- def check_typedef(self, fname, name, args):
- return True
-
def msg(self, fname, name, args):
self.data = ""

@@ -306,7 +297,7 @@ class RestFormat(OutputFormat):
for line in output.strip("\n").split("\n"):
self.data += self.lineprefix + line + "\n"

- def out_section(self, args, out_reference=False):
+ def out_section(self, args, out_docblock=False):
"""
Outputs a block section.

@@ -325,7 +316,7 @@ class RestFormat(OutputFormat):
continue

if not self.out_mode == self.OUTPUT_INCLUDE:
- if out_reference:
+ if out_docblock:
self.data += f".. _{section}:\n\n"

if not self.symbol:
@@ -339,8 +330,7 @@ class RestFormat(OutputFormat):
def out_doc(self, fname, name, args):
if not self.check_doc(name):
return
-
- self.out_section(args, out_reference=True)
+ self.out_section(args, out_docblock=True)

def out_function(self, fname, name, args):

@@ -583,8 +573,10 @@ class ManFormat(OutputFormat):

for line in contents.strip("\n").split("\n"):
line = Re(r"^\s*").sub("", line)
+ if not line:
+ continue

- if line and line[0] == ".":
+ if line[0] == ".":
self.data += "\\&" + line + "\n"
else:
self.data += line + "\n"
@@ -594,6 +586,9 @@ class ManFormat(OutputFormat):
sectionlist = args.get('sectionlist', [])
sections = args.get('sections', {})

+ if not self.check_doc(name):
+ return
+
self.data += f'.TH "{module}" 9 "{module}" "{self.man_date}" "API Manual" LINUX' + "\n"

for section in sectionlist:
diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index e8c86448d6b5..74b311c8184c 100755
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -1198,6 +1198,7 @@ class KernelDoc:
else:
self.entry.section = doc_block.group(1)

+ self.entry.identifier = self.entry.section
self.state = self.STATE_DOCBLOCK
return

@@ -1628,7 +1629,7 @@ class KernelDoc:

if doc_end.search(line):
self.dump_section()
- self.output_declaration("doc", None,
+ self.output_declaration("doc", self.entry.identifier,
sectionlist=self.entry.sectionlist,
sections=self.entry.sections,
section_start_lines=self.entry.section_start_lines,
--
2.49.0