[PATCH 23/27] scripts/kernel-doc.py: postpone warnings to the output plugin
From: Mauro Carvalho Chehab
Date: Wed Feb 19 2025 - 03:35:25 EST
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@xxxxxxxxxx>
---
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 ca21cd856be4..7aeaec884545 100755
--- a/scripts/lib/kdoc/kdoc_output.py
+++ b/scripts/lib/kdoc/kdoc_output.py
@@ -115,7 +115,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:
@@ -125,19 +134,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]:
@@ -146,9 +158,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
@@ -162,7 +176,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":
@@ -327,7 +341,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)
@@ -585,7 +599,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 116289622f2c..a71145d531f2 100755
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -130,23 +130,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):
"""
@@ -220,10 +220,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
@@ -256,6 +255,8 @@ class KernelDoc:
self.entry.struct_actual = ""
self.entry.prototype = ""
+ self.entry.warnings = []
+
self.entry.parameterlist = []
self.entry.parameterdescs = {}
self.entry.parametertypes = {}
@@ -327,7 +328,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:
@@ -867,16 +868,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.48.1