[PATCH v4 1/4] scripts/kernel-doc: fix logic to handle unissued warnings

[PATCH v4 1/4] scripts/kernel-doc: fix logic to handle unissued warnings

[Mauro Carvalho Chehab]

Changeset 469c1c9eb6c9 ("kernel-doc: Issue warnings that were silently discarded")
didn't properly addressed the missing messages behavior, as
it was calling directly python logger low-level function,
instead of using the expected method to emit warnings.

Basically, there are two methods to log messages:

- self.config.log.warning() - This is the raw level to emit a
  warning. It just writes the a message at stderr, via python
  logging, as it is initialized as:

    self.config.log = logging.getLogger("kernel-doc")

- self.config.warning() - This is where we actually consider a
  message as a warning, properly incrementing error count.

Due to that, several parsing error messages are internally considered
as success, causing -Werror to not work on such messages.

While here, ensure that the last ignored entry will also be handled
by adding an extra check at the end of the parse handler.

Fixes: 469c1c9eb6c9 ("kernel-doc: Issue warnings that were silently discarded")
Closes: https://lore.kernel.org/linux-doc/20260112091053.00cee29a@foz.lan/
Cc: stable@vger.kernel.org
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
 tools/lib/python/kdoc/kdoc_parser.py | 31 ++++++++++++++++++++++------
 1 file changed, 25 insertions(+), 6 deletions(-)

diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index a9a37519145d..4ad7ce0b243e 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -448,18 +448,35 @@ class KernelDoc:
 
         self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
 
+    def emit_unused_warnings(self):
+        """
+        When the parser fails to produce a valid entry, it places some
+        warnings under `entry.warnings` that will be discarded when resetting
+        the state.
+
+        Ensure that those warnings are not lost.
+
+        NOTE: Because we are calling `config.warning()` here, those
+              warnings are not filtered by the `-W` parameters: they will all
+              be produced even when `-Wreturn`, `-Wshort-desc`, and/or
+              `-Wcontents-before-sections` are used.
+
+              Allowing those warnings to be filtered is complex, because it
+              would require storing them in a buffer and then filtering them
+              during the output step of the code, depending on the
+              selected symbols.
+        """
+        if self.entry and self.entry not in self.entries:
+            for log_msg in self.entry.warnings:
+                self.config.warning(log_msg)
+
     def reset_state(self, ln):
         """
         Ancillary routine to create a new entry. It initializes all
         variables used by the state machine.
         """
 
-        #
-        # Flush the warnings out before we proceed further
-        #
-        if self.entry and self.entry not in self.entries:
-            for log_msg in self.entry.warnings:
-                self.config.log.warning(log_msg)
+        self.emit_unused_warnings()
 
         self.entry = KernelEntry(self.config, self.fname, ln)
 
@@ -1741,6 +1758,8 @@ class KernelDoc:
                         # Hand this line to the appropriate state handler
                         self.state_actions[self.state](self, ln, line)
 
+            self.emit_unused_warnings()
+
         except OSError:
             self.config.log.error(f"Error: Cannot open file {self.fname}")
 
-- 
2.52.0

[PATCH v4 2/4] scripts/kernel-doc: avoid error_count overflows

[Mauro Carvalho Chehab]

The glibc library limits the return code to 8 bits. We need to
stick to this limit when using sys.exit(error_count).

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: stable@vger.kernel.org
---
 scripts/kernel-doc.py | 25 ++++++++++++++++++-------
 1 file changed, 18 insertions(+), 7 deletions(-)

diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index 7a1eaf986bcd..3992ca49d593 100755
--- a/scripts/kernel-doc.py
+++ b/scripts/kernel-doc.py
@@ -116,6 +116,8 @@ SRC_DIR = os.path.dirname(os.path.realpath(__file__))
 
 sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
 
+WERROR_RETURN_CODE = 3
+
 DESC = """
 Read C language source or header FILEs, extract embedded documentation comments,
 and print formatted documentation to standard output.
@@ -176,7 +178,20 @@ class MsgFormatter(logging.Formatter):
         return logging.Formatter.format(self, record)
 
 def main():
-    """Main program"""
+    """
+    Main program
+    By default, the return value is:
+
+    - 0: success or Python version is not compatible with                                                                kernel-doc.  If -Werror is not used, it will also
+       return 0 if there are issues at kernel-doc markups;
+
+    - 1: an abnormal condition happened;
+
+    - 2: argparse issued an error;
+
+    - 3: -Werror is used, and one or more unfiltered parse warnings
+         happened.
+    """
 
     parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
                                      description=DESC)
@@ -323,16 +338,12 @@ def main():
 
     if args.werror:
         print("%s warnings as errors" % error_count)    # pylint: disable=C0209
-        sys.exit(error_count)
+        sys.exit(WERROR_RETURN_CODE)
 
     if args.verbose:
         print("%s errors" % error_count)                # pylint: disable=C0209
 
-    if args.none:
-        sys.exit(0)
-
-    sys.exit(error_count)
-
+    sys.exit(0)
 
 # Call main method
 if __name__ == "__main__":
-- 
2.52.0

Re: [PATCH v4 2/4] scripts/kernel-doc: avoid error_count overflows

[Randy Dunlap]

Mauro,
The line formatting is weird on one line below
(looks like 2 text lines are joined).

On 1/14/26 4:57 AM, Mauro Carvalho Chehab wrote:
> The glibc library limits the return code to 8 bits. We need to
> stick to this limit when using sys.exit(error_count).
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Cc: stable@vger.kernel.org
> ---
>  scripts/kernel-doc.py | 25 ++++++++++++++++++-------
>  1 file changed, 18 insertions(+), 7 deletions(-)
> 
> diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
> index 7a1eaf986bcd..3992ca49d593 100755
> --- a/scripts/kernel-doc.py
> +++ b/scripts/kernel-doc.py
> @@ -116,6 +116,8 @@ SRC_DIR = os.path.dirname(os.path.realpath(__file__))
>  
>  sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
>  
> +WERROR_RETURN_CODE = 3
> +
>  DESC = """
>  Read C language source or header FILEs, extract embedded documentation comments,
>  and print formatted documentation to standard output.
> @@ -176,7 +178,20 @@ class MsgFormatter(logging.Formatter):
>          return logging.Formatter.format(self, record)
>  
>  def main():
> -    """Main program"""
> +    """
> +    Main program
> +    By default, the return value is:
> +
> +    - 0: success or Python version is not compatible with                                                                kernel-doc.  If -Werror is not used, it will also

Here ^^^^^

> +       return 0 if there are issues at kernel-doc markups;
> +
> +    - 1: an abnormal condition happened;


-- 
~Randy

Re: [PATCH v4 2/4] scripts/kernel-doc: avoid error_count overflows

[Jonathan Corbet]

Randy Dunlap <rdunlap@infradead.org> writes:

> Mauro,
> The line formatting is weird on one line below
> (looks like 2 text lines are joined).
>
> On 1/14/26 4:57 AM, Mauro Carvalho Chehab wrote:
>> The glibc library limits the return code to 8 bits. We need to
>> stick to this limit when using sys.exit(error_count).
>> 
>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>> Cc: stable@vger.kernel.org
>> ---
>>  scripts/kernel-doc.py | 25 ++++++++++++++++++-------
>>  1 file changed, 18 insertions(+), 7 deletions(-)
>> 
>> diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
>> index 7a1eaf986bcd..3992ca49d593 100755
>> --- a/scripts/kernel-doc.py
>> +++ b/scripts/kernel-doc.py
>> @@ -116,6 +116,8 @@ SRC_DIR = os.path.dirname(os.path.realpath(__file__))
>>  
>>  sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
>>  
>> +WERROR_RETURN_CODE = 3
>> +
>>  DESC = """
>>  Read C language source or header FILEs, extract embedded documentation comments,
>>  and print formatted documentation to standard output.
>> @@ -176,7 +178,20 @@ class MsgFormatter(logging.Formatter):
>>          return logging.Formatter.format(self, record)
>>  
>>  def main():
>> -    """Main program"""
>> +    """
>> +    Main program
>> +    By default, the return value is:
>> +
>> +    - 0: success or Python version is not compatible with                                                                kernel-doc.  If -Werror is not used, it will also
>
> Here ^^^^^
>
Mauro, can you get me a clean copy?  It seems like we're more than ready
to apply this set otherwise...

Thanks,

jon

Re: [PATCH v4 2/4] scripts/kernel-doc: avoid error_count overflows

[Mauro Carvalho Chehab]

Em Fri, 16 Jan 2026 11:17:28 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> Randy Dunlap <rdunlap@infradead.org> writes:
> 
> > Mauro,
> > The line formatting is weird on one line below
> > (looks like 2 text lines are joined).
> >
> > On 1/14/26 4:57 AM, Mauro Carvalho Chehab wrote:  
> >> The glibc library limits the return code to 8 bits. We need to
> >> stick to this limit when using sys.exit(error_count).
> >> 
> >> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> >> Cc: stable@vger.kernel.org
> >> ---
> >>  scripts/kernel-doc.py | 25 ++++++++++++++++++-------
> >>  1 file changed, 18 insertions(+), 7 deletions(-)
> >> 
> >> diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
> >> index 7a1eaf986bcd..3992ca49d593 100755
> >> --- a/scripts/kernel-doc.py
> >> +++ b/scripts/kernel-doc.py
> >> @@ -116,6 +116,8 @@ SRC_DIR = os.path.dirname(os.path.realpath(__file__))
> >>  
> >>  sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
> >>  
> >> +WERROR_RETURN_CODE = 3
> >> +
> >>  DESC = """
> >>  Read C language source or header FILEs, extract embedded documentation comments,
> >>  and print formatted documentation to standard output.
> >> @@ -176,7 +178,20 @@ class MsgFormatter(logging.Formatter):
> >>          return logging.Formatter.format(self, record)
> >>  
> >>  def main():
> >> -    """Main program"""
> >> +    """
> >> +    Main program
> >> +    By default, the return value is:
> >> +
> >> +    - 0: success or Python version is not compatible with                                                                kernel-doc.  If -Werror is not used, it will also  
> >
> > Here ^^^^^
> >  
> Mauro, can you get me a clean copy?  It seems like we're more than ready
> to apply this set otherwise...

Just sent.

Ah, if you're curiously enough about autodoc, and don't want to apply
the /15 patch series, or just want to check if the docstrings are OK,
you can apply the enclosed test patch. I'm not proposing adding it
to the series, but getting issues like the above where comments look
weird is better caught by checking if the docstrings are properly
formatted and parsed by Sphinx.

Thanks,
Mauro

---

[HACK] Python autodoc test

This is just a minimal patch to place kernel-doc API documentation
somewhere (at the wrong place).

Goal here is just to easily allow testing autodoc.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 1ea2ae5c6276..bf16dd68bc62 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -18,6 +18,9 @@ import sphinx
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath("sphinx"))
 
+# Allow sphinx.ext.autodoc to document any pyhton files within the Kernel tree
+sys.path.append(os.path.abspath(".."))
+
 # Minimal supported version
 needs_sphinx = "3.4.3"
 
@@ -151,6 +154,7 @@ extensions = [
     "maintainers_include",
     "parser_yaml",
     "rstFlatTable",
+    "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.ifconfig",
     "translations",
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index b56128d7f5c3..7884c1297513 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -624,3 +624,11 @@ using SPHINXDIRS:
 
    When SPHINXDIRS={subdir} is used, it will only generate man pages for
    the files explicitly inside a ``Documentation/{subdir}/.../*.rst`` file.
+
+kernel\-doc docstrings documentation
+------------------------------------
+
+.. automodule:: scripts.kernel_doc
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 3b6ef807791a..47eaae84adeb 120000
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1 +1 @@
-kernel-doc.py
\ No newline at end of file
+kernel_doc.py
\ No newline at end of file
diff --git a/scripts/kernel-doc.py b/scripts/kernel_doc.py
similarity index 100%
rename from scripts/kernel-doc.py
rename to scripts/kernel_doc.py