[PATCH v3 17/33] scripts/kernel-doc.py: postpone warnings to the output plugin

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

We don't want to have warnings displayed for symbols that
weren't output. So, postpone warnings print to the output
plugin, where symbol output is validated.

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

diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output.py
index d0c8cedb0ea5..6582d1f64d1e 100755
--- a/scripts/lib/kdoc/kdoc_output.py
+++ b/scripts/lib/kdoc/kdoc_output.py
@@ -116,7 +116,16 @@ class OutputFormat:

return block

- def check_doc(self, name):
+ def out_warnings(self, args):
+ warnings = args.get('warnings', [])
+
+ for warning, log_msg in warnings:
+ if warning:
+ self.config.log.warning(log_msg)
+ else:
+ self.config.log.info(log_msg)
+
+ def check_doc(self, name, args):
"""Check if DOC should be output"""

if self.no_doc_sections:
@@ -126,19 +135,22 @@ class OutputFormat:
return False

if self.out_mode == self.OUTPUT_ALL:
+ self.out_warnings(args)
return True

if self.out_mode == self.OUTPUT_INCLUDE:
if name in self.function_table:
+ self.out_warnings(args)
return True

return False

- def check_declaration(self, dtype, name):
+ def check_declaration(self, dtype, name, args):
if name in self.nosymbol:
return False

if self.out_mode == self.OUTPUT_ALL:
+ self.out_warnings(args)
return True

if self.out_mode in [self.OUTPUT_INCLUDE, self.OUTPUT_EXPORTED]:
@@ -147,9 +159,11 @@ class OutputFormat:

if self.out_mode == self.OUTPUT_INTERNAL:
if dtype != "function":
+ self.out_warnings(args)
return True

if name not in self.function_table:
+ self.out_warnings(args)
return True

return False
@@ -163,7 +177,7 @@ class OutputFormat:
self.out_doc(fname, name, args)
return self.data

- if not self.check_declaration(dtype, name):
+ if not self.check_declaration(dtype, name, args):
return self.data

if dtype == "function":
@@ -328,7 +342,7 @@ class RestFormat(OutputFormat):
self.data += "\n"

def out_doc(self, fname, name, args):
- if not self.check_doc(name):
+ if not self.check_doc(name, args):
return
self.out_section(args, out_docblock=True)

@@ -586,7 +600,7 @@ class ManFormat(OutputFormat):
sectionlist = args.get('sectionlist', [])
sections = args.get('sections', {})

- if not self.check_doc(name):
+ if not self.check_doc(name, args):
return

self.data += f'.TH "{module}" 9 "{module}" "{self.man_date}" "API Manual" LINUX' + "\n"
diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index 74b311c8184c..3698ef625367 100755
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -131,23 +131,23 @@ class KernelDoc:
# Place all potential outputs into an array
self.entries = []

- def show_warnings(self, dtype, declaration_name): # pylint: disable=W0613
- """
- Allow filtering out warnings
- """
-
- # TODO: implement it
-
- return True
-
# TODO: rename to emit_message
def emit_warning(self, ln, msg, warning=True):
"""Emit a message"""

+ log_msg = f"{self.fname}:{ln} {msg}"
+
+ if self.entry:
+ # Delegate warning output to output logic, as this way it
+ # will report warnings/info only for symbols that are output
+
+ self.entry.warnings.append((warning, log_msg))
+ return
+
if warning:
- self.config.log.warning("%s:%d %s", self.fname, ln, msg)
+ self.config.log.warning(log_msg)
else:
- self.config.log.info("%s:%d %s", self.fname, ln, msg)
+ self.config.log.info(log_msg)

def dump_section(self, start_new=True):
"""
@@ -221,10 +221,9 @@ class KernelDoc:
# For now, we're keeping the same name of the function just to make
# easier to compare the source code of both scripts

- if "declaration_start_line" not in args:
- args["declaration_start_line"] = self.entry.declaration_start_line
-
+ args["declaration_start_line"] = self.entry.declaration_start_line
args["type"] = dtype
+ args["warnings"] = self.entry.warnings

# TODO: use colletions.OrderedDict

@@ -257,6 +256,8 @@ class KernelDoc:
self.entry.struct_actual = ""
self.entry.prototype = ""

+ self.entry.warnings = []
+
self.entry.parameterlist = []
self.entry.parameterdescs = {}
self.entry.parametertypes = {}
@@ -328,7 +329,7 @@ class KernelDoc:
if param not in self.entry.parameterdescs and not param.startswith("#"):
self.entry.parameterdescs[param] = self.undescribed

- if self.show_warnings(dtype, declaration_name) and "." not in param:
+ if "." not in param:
if decl_type == 'function':
dname = f"{decl_type} parameter"
else:
@@ -868,16 +869,14 @@ class KernelDoc:
self.entry.parameterlist.append(arg)
if arg not in self.entry.parameterdescs:
self.entry.parameterdescs[arg] = self.undescribed
- if self.show_warnings("enum", declaration_name):
- self.emit_warning(ln,
- f"Enum value '{arg}' not described in enum '{declaration_name}'")
+ self.emit_warning(ln,
+ f"Enum value '{arg}' not described in enum '{declaration_name}'")
member_set.add(arg)

for k in self.entry.parameterdescs:
if k not in member_set:
- if self.show_warnings("enum", declaration_name):
- self.emit_warning(ln,
- f"Excess enum value '%{k}' description in '{declaration_name}'")
+ self.emit_warning(ln,
+ f"Excess enum value '%{k}' description in '{declaration_name}'")

self.output_declaration('enum', declaration_name,
enum=declaration_name,
--
2.49.0