[PATCH v3 28/33] scripts/kernel-doc.py: Properly handle Werror and exit codes

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

The original kernel-doc script has a logic to return warnings
as errors, and to report the number of warnings found, if in
verbose mode.

Implement it to be fully compatible with the original script.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/kernel-doc.py | 18 ++++++++++++++++--
scripts/lib/kdoc/kdoc_files.py | 12 ++++++++++--
scripts/lib/kdoc/kdoc_output.py | 8 +++-----
scripts/lib/kdoc/kdoc_parser.py | 15 ++++++---------
4 files changed, 35 insertions(+), 18 deletions(-)

diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index 6a6bc81efd31..2f2fad813024 100755
--- a/scripts/kernel-doc.py
+++ b/scripts/kernel-doc.py
@@ -78,8 +78,6 @@
# Yacine Belkadi <yacine.belkadi.1@gmail.com>
# Yujie Liu <yujie.liu@intel.com>

-# TODO: implement warning filtering
-
"""
kernel_doc
==========
@@ -295,6 +293,22 @@ def main():
if msg:
print(msg)

+ error_count = kfiles.errors
+ if not error_count:
+ sys.exit(0)
+
+ if args.werror:
+ print(f"{error_count} warnings as errors")
+ sys.exit(error_count)
+
+ if args.verbose:
+ print(f"{error_count} errors")
+
+ if args.none:
+ sys.exit(0)
+
+ sys.exit(error_count)
+

# Call main method
if __name__ == "__main__":
diff --git a/scripts/lib/kdoc/kdoc_files.py b/scripts/lib/kdoc/kdoc_files.py
index e52a6d05237e..182d9ed58a72 100644
--- a/scripts/lib/kdoc/kdoc_files.py
+++ b/scripts/lib/kdoc/kdoc_files.py
@@ -12,7 +12,6 @@ import argparse
import logging
import os
import re
-import sys

from kdoc_parser import KernelDoc
from kdoc_output import OutputFormat
@@ -109,7 +108,7 @@ class KernelFiles():
KernelDoc.process_export(self.config.function_table, line)

except IOError:
- print(f"Error: Cannot open fname {fname}", fname=sys.stderr)
+ self.config.log.error("Error: Cannot open fname %s", fname)
self.config.errors += 1

def file_not_found_cb(self, fname):
@@ -262,3 +261,12 @@ class KernelFiles():
fname, ln, dtype)
if msg:
yield fname, msg
+
+ @property
+ def errors(self):
+ """
+ Return a count of the number of warnings found, including
+ the ones displayed while interacting over self.msg.
+ """
+
+ return self.config.errors
diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output.py
index eb013075da84..e9b4d0093084 100755
--- a/scripts/lib/kdoc/kdoc_output.py
+++ b/scripts/lib/kdoc/kdoc_output.py
@@ -128,11 +128,9 @@ class OutputFormat:

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)
+ for log_msg in warnings:
+ self.config.log.warning(log_msg)
+ self.config.errors += 1

def check_doc(self, name, args):
"""Check if DOC should be output"""
diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index 77e8bfeccc8e..43e6ffbdcc2c 100755
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -137,17 +137,18 @@ class KernelDoc:

log_msg = f"{self.fname}:{ln} {msg}"

+ if not warning:
+ self.config.log.info(log_msg)
+ return
+
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))
+ self.entry.warnings.append(log_msg)
return

- if warning:
- self.config.log.warning(log_msg)
- else:
- self.config.log.info(log_msg)
+ self.config.log.warning(log_msg)

def dump_section(self, start_new=True):
"""
@@ -556,7 +557,6 @@ class KernelDoc:

if not members:
self.emit_warning(ln, f"{proto} error: Cannot parse struct or union!")
- self.config.errors += 1
return

if self.entry.identifier != declaration_name:
@@ -831,7 +831,6 @@ class KernelDoc:

if not members:
self.emit_warning(ln, f"{proto}: error: Cannot parse enum!")
- self.config.errors += 1
return

if self.entry.identifier != declaration_name:
@@ -1132,7 +1131,6 @@ class KernelDoc:
return

self.emit_warning(ln, "error: Cannot parse typedef!")
- self.config.errors += 1

@staticmethod
def process_export(function_table, line):
@@ -1677,4 +1675,3 @@ class KernelDoc:
self.process_docblock(ln, line)
except OSError:
self.config.log.error(f"Error: Cannot open file {self.fname}")
- self.config.errors += 1
--
2.49.0