linux-kernel - Re: [PATCH v4 2/4] scripts/kernel-doc: avoid error

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20260117105205.14eea6e3@foz.lan>
Date: Sat, 17 Jan 2026 10:52:05 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: Randy Dunlap <rdunlap@...radead.org>, Linux Doc Mailing List
 <linux-doc@...r.kernel.org>, Mauro Carvalho Chehab <mchehab@...nel.org>,
 linux-kernel@...r.kernel.org, Jani Nikula <jani.nikula@...el.com>, Shuah
 Khan <skhan@...uxfoundation.org>, stable@...r.kernel.org
Subject: Re: [PATCH v4 2/4] scripts/kernel-doc: avoid error_count overflows

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

> Randy Dunlap <rdunlap@...radead.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@...nel.org>
> >> Cc: stable@...r.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@...nel.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