summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab+huawei@kernel.org>2025-04-08 18:09:20 +0800
committerJonathan Corbet <corbet@lwn.net>2025-04-09 12:10:33 -0600
commit9cbc2d3b137bfdb7937265c46e9e5d7e72952841 (patch)
treeab4d3a2a594fa5763c6801634f3dce9d0c973000
parent9235ec5e2bf8ccd3f3ef30bbb1811bf9ddb3ef08 (diff)
scripts/kernel-doc.py: postpone warnings to the output plugin
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> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/e6344711e390cf22af02a56bb5dd51ca67c0afb6.1744106242.git.mchehab+huawei@kernel.org
-rwxr-xr-xscripts/lib/kdoc/kdoc_output.py24
-rwxr-xr-xscripts/lib/kdoc/kdoc_parser.py41
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,