[PATCH v3 0/4] fix -Werror issues

[PATCH v3 0/4] fix -Werror issues

[Mauro Carvalho Chehab]

Hi Jon,

As pointed by Jani, and previously by Randy, several warnings
are currently not considered as errors. The issue is related
to changeset 469c1c9eb6c9 ("kernel-doc: Issue warnings that were silently
discarded"), which was using directly a low-level interface.

Patch 1 fix that.
Patch 2 fixes a related issue: when there are more than 255
errors, the return code with -Werror can be 0 even on errors,
because of glibc behavior: programs can only use 8 bits for
error codes.

Patches 3 and 4 are not directly related, and touches only
on comments inside python-doc.py script itself:

- patch 3 is just a coding style change to match the comment
  style we agreed;

- patch 4 fixes some English issues on comments. The issues
  were pointed by LLM, which was used as any other spelling
  tool: I picked just the relevant changes, ignoring the ones
  that were false positives. I also didn't agree with one of
  the changes, replacing it by something else.

  I wrote it more as an experiment about how to properly use
  LLM. IMO, it could be useful to use LLM to review spelling
  on docs, provided that the one using the tool will filter
  out LLM-generated trash - just like one does when using any
  other spelling tool. Yet, based on Jani feedback, extra
  care is needed with regards to LLM abuse of UTF-8 chars.

---

v3:
  - did some cleanups at patch 1, placing the code on a new
    function;
  - removed extra blank line after comments

v2:
  - on patch 2, I changed the -Werror return code to "3". This
    way, it is easier for a script to identify what happened;
  - removed UTF-8 unbreakable whitespaces from patch 4.
    Heh, it seems that LLM-produced stuff can suffer with
    unwanted UTF-8 chars... On one of the strings it replaced
    0x20 with 0xa0...



Mauro Carvalho Chehab (4):
  scripts/kernel-doc: fix logic to handle unissued warnings
  scripts/kernel-doc: avoid error_count overflows
  scripts/kernel-doc: ensure that comments are using our coding style
  scripts/kernel-doc: some fixes to kernel-doc comments

 scripts/kernel-doc.py                | 72 ++++++++++++++++++----------
 tools/lib/python/kdoc/kdoc_parser.py | 31 +++++++++---
 2 files changed, 73 insertions(+), 30 deletions(-)

-- 
2.52.0

[PATCH v3 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 v3 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 | 26 +++++++++++++++++++-------
 1 file changed, 19 insertions(+), 7 deletions(-)

diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index 7a1eaf986bcd..5d2f29e90ebe 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,21 @@ class MsgFormatter(logging.Formatter):
         return logging.Formatter.format(self, record)
 
 def main():
-    """Main program"""
+    """
+    Main program
+    By default, the return value is:
+
+    - 0: parsing warnings or Python version is not compatible with
+      kernel-doc. The rationale for the latter is to not break Linux
+      compilation on such cases;
+
+    - 1: an abnormal condition happened;
+
+    - 2: arparse 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 +339,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

[PATCH v3 3/4] scripts/kernel-doc: ensure that comments are using our coding style

[Mauro Carvalho Chehab]

Along kernel-doc libs, we opted to have all comments starting/ending
with a blank comment line. Use the same style here.

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

diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index 5d2f29e90ebe..da06184cbd8b 100755
--- a/scripts/kernel-doc.py
+++ b/scripts/kernel-doc.py
@@ -3,7 +3,7 @@
 # Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@kernel.org>.
 #
 # pylint: disable=C0103,R0912,R0914,R0915
-
+#
 # NOTE: While kernel-doc requires at least version 3.6 to run, the
 #       command line should work with Python 3.2+ (tested with 3.4).
 #       The rationale is that it shall fail gracefully during Kernel
@@ -12,7 +12,7 @@
 #       - no f-strings can be used on this file.
 #       - the libraries that require newer versions can only be included
 #         after Python version is checked.
-
+#
 # Converted from the kernel-doc script originally written in Perl
 # under GPLv2, copyrighted since 1998 by the following authors:
 #
@@ -197,8 +197,9 @@ def main():
     parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
                                      description=DESC)
 
+    #
     # Normal arguments
-
+    #
     parser.add_argument("-v", "-verbose", "--verbose", action="store_true",
                         help="Verbose output, more warnings and other information.")
 
@@ -213,8 +214,9 @@ def main():
                         action="store_true",
                         help="Enable line number output (only in ReST mode)")
 
+    #
     # Arguments to control the warning behavior
-
+    #
     parser.add_argument("-Wreturn", "--wreturn", action="store_true",
                         help="Warns about the lack of a return markup on functions.")
 
@@ -235,8 +237,9 @@ def main():
     parser.add_argument("-export-file", "--export-file", action='append',
                         help=EXPORT_FILE_DESC)
 
+    #
     # Output format mutually-exclusive group
-
+    #
     out_group = parser.add_argument_group("Output format selection (mutually exclusive)")
 
     out_fmt = out_group.add_mutually_exclusive_group()
@@ -248,8 +251,9 @@ def main():
     out_fmt.add_argument("-N", "-none", "--none", action="store_true",
                          help="Do not output documentation, only warnings.")
 
+    #
     # Output selection mutually-exclusive group
-
+    #
     sel_group = parser.add_argument_group("Output selection (mutually exclusive)")
     sel_mut = sel_group.add_mutually_exclusive_group()
 
@@ -262,7 +266,9 @@ def main():
     sel_mut.add_argument("-s", "-function", "--symbol", action='append',
                          help=FUNCTION_DESC)
 
+    #
     # Those are valid for all 3 types of filter
+    #
     parser.add_argument("-n", "-nosymbol", "--nosymbol", action='append',
                         help=NOSYMBOL_DESC)
 
@@ -295,9 +301,11 @@ def main():
 
     python_ver = sys.version_info[:2]
     if python_ver < (3,6):
+        #
         # Depending on Kernel configuration, kernel-doc --none is called at
         # build time. As we don't want to break compilation due to the
         # usage of an old Python version, return 0 here.
+        #
         if args.none:
             logger.error("Python 3.6 or later is required by kernel-doc. skipping checks")
             sys.exit(0)
@@ -307,7 +315,9 @@ def main():
     if python_ver < (3,7):
         logger.warning("Python 3.7 or later is required for correct results")
 
+    #
     # Import kernel-doc libraries only after checking Python version
+    #
     from kdoc.kdoc_files import KernelFiles             # pylint: disable=C0415
     from kdoc.kdoc_output import RestFormat, ManFormat  # pylint: disable=C0415
 
@@ -346,6 +356,8 @@ def main():
 
     sys.exit(0)
 
+#
 # Call main method
+#
 if __name__ == "__main__":
     main()
-- 
2.52.0

[PATCH v3 4/4] scripts/kernel-doc: some fixes to kernel-doc comments

[Mauro Carvalho Chehab]

There are some typos and English errors at the kernel-doc.py comments.

Locate them with the help of LLM (gpt-oss 14B), locally excecuted
with this prompt:

    review English grammar andsyntax at the comments on the code
    below:
    <cat scripts/kernel-doc.py>

Not all results are flowers, although it caught several minor
issues there. Add the pertinent fixes, discarding the bad ones.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc.py | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index da06184cbd8b..4998a79ea6d1 100755
--- a/scripts/kernel-doc.py
+++ b/scripts/kernel-doc.py
@@ -9,9 +9,9 @@
 #       The rationale is that it shall fail gracefully during Kernel
 #       compilation with older Kernel versions. Due to that:
 #       - encoding line is needed here;
-#       - no f-strings can be used on this file.
-#       - the libraries that require newer versions can only be included
-#         after Python version is checked.
+#       - f-strings cannot be used in this file.
+#       - libraries that require newer versions can only be included
+#         after the Python version has been checked.
 #
 # Converted from the kernel-doc script originally written in Perl
 # under GPLv2, copyrighted since 1998 by the following authors:
@@ -134,13 +134,13 @@ May be used multiple times.
 """
 
 EXPORT_DESC = """
-Only output documentation for the symbols that have been
+Only output documentation for symbols that have been
 exported using EXPORT_SYMBOL() and related macros in any input
 FILE or -export-file FILE.
 """
 
 INTERNAL_DESC = """
-Only output documentation for the symbols that have NOT been
+Only output documentation for symbols that have NOT been
 exported using EXPORT_SYMBOL() and related macros in any input
 FILE or -export-file FILE.
 """
@@ -163,7 +163,7 @@ Header and C source files to be parsed.
 """
 
 WARN_CONTENTS_BEFORE_SECTIONS_DESC = """
-Warns if there are contents before sections (deprecated).
+Warn if there are contents before sections (deprecated).
 
 This option is kept just for backward-compatibility, but it does nothing,
 neither here nor at the original Perl script.
@@ -171,7 +171,7 @@ neither here nor at the original Perl script.
 
 
 class MsgFormatter(logging.Formatter):
-    """Helper class to format warnings on a similar way to kernel-doc.pl"""
+    """Helper class to format warnings in a similar way to kernel-doc.pl."""
 
     def format(self, record):
         record.levelname = record.levelname.capitalize()
@@ -273,7 +273,7 @@ def main():
                         help=NOSYMBOL_DESC)
 
     parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections",
-                        action='store_true', help="Don't outputt DOC sections")
+                        action='store_true', help="Don't output DOC sections")
 
     parser.add_argument("files", metavar="FILE",
                         nargs="+", help=FILES_DESC)
@@ -302,12 +302,12 @@ def main():
     python_ver = sys.version_info[:2]
     if python_ver < (3,6):
         #
-        # Depending on Kernel configuration, kernel-doc --none is called at
+        # Depending on the Kernel configuration, kernel-doc --none is called at
         # build time. As we don't want to break compilation due to the
         # usage of an old Python version, return 0 here.
         #
         if args.none:
-            logger.error("Python 3.6 or later is required by kernel-doc. skipping checks")
+            logger.error("Python 3.6 or later is required by kernel-doc. Skipping checks")
             sys.exit(0)
 
         sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.")
@@ -316,7 +316,7 @@ def main():
         logger.warning("Python 3.7 or later is required for correct results")
 
     #
-    # Import kernel-doc libraries only after checking Python version
+    # Import kernel-doc libraries only after checking the Python version
     #
     from kdoc.kdoc_files import KernelFiles             # pylint: disable=C0415
     from kdoc.kdoc_output import RestFormat, ManFormat  # pylint: disable=C0415
-- 
2.52.0

Re: [PATCH v3 4/4] scripts/kernel-doc: some fixes to kernel-doc comments

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> There are some typos and English errors at the kernel-doc.py comments.
>
> Locate them with the help of LLM (gpt-oss 14B), locally excecuted
> with this prompt:
>
>     review English grammar andsyntax at the comments on the code
>     below:
>     <cat scripts/kernel-doc.py>
>
> Not all results are flowers, although it caught several minor
> issues there. Add the pertinent fixes, discarding the bad ones.

"flowers"?  Did the LLM put that out too? :)

The changes themselves look fine.

Thanks,

jon

Re: [PATCH v3 4/4] scripts/kernel-doc: some fixes to kernel-doc comments

[Mauro Carvalho Chehab]

Em Tue, 13 Jan 2026 13:55:18 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > There are some typos and English errors at the kernel-doc.py comments.
> >
> > Locate them with the help of LLM (gpt-oss 14B), locally excecuted
> > with this prompt:
> >
> >     review English grammar andsyntax at the comments on the code
> >     below:
> >     <cat scripts/kernel-doc.py>
> >
> > Not all results are flowers, although it caught several minor
> > issues there. Add the pertinent fixes, discarding the bad ones.  
> 
> "flowers"?  Did the LLM put that out too? :)

No, you should blame me for the description ;-) I didn't ask LLM
to write it for me. On past experiments, LLM is not great writing
texts - specially with open models that run fine with 16GB VRAM.
I might have asked it to review(*).

I was trying to say that: while LLM worked fine for the task of
doing an English grammar review for the strings, being able to
distinguish them from the actual code, it was not is perfect: 
some things required manual work to fix.

(*) asking it to review with this prompt:

	"review the test below and produce a version with English spelling fixed:
	 <patch description>"

Gave:

	"There are some typos and English errors in the comments of kernel‑doc.py.

	 Locate them with the help of an LLM (gpt‑oss 14B), executed locally with this prompt:
 
	review English grammar and syntax at the comments on the code below:
	<cat scripts/kernel-doc.py>

	Not all results are perfect, although the LLM caught several minor issues.
	Add the relevant fixes, discarding the incorrect ones."

Asking it to explain what changed with:

	"what changes you did? why?"  (**)

using ollama with gpt-oss:latest (14B) gave:

<llm_output>
Changes I made to the test text
-------------------------------

+---+---------------------+-----------------+--------------------------+
| # | Original phrase     | Fixed phrase    | Why it was changed       |
+===+=====================+=================+==========================+
| 1 | ``excecuted``       | ``executed``    | Misspelling of           |
|   |                     |                 | *executed*.              |
+---+---------------------+-----------------+--------------------------+
| 2 | ``synatx``          | ``syntax``      | Misspelling of *syntax*. |
+---+---------------------+-----------------+--------------------------+
| 3 | ``review English    | ``review        | Added a space between    |
|   | grammar andsyntax`` | English grammar | *grammar* and *syntax*   |
|   |                     | and syntax``    | and kept the             |
|   |                     |                 | capitalization           |
|   |                     |                 | consistent.              |
+---+---------------------+-----------------+--------------------------+
| 4 | ``there.``          | ``there.`` (no  | The original had an      |
|   |                     | change needed)  | extraneous period after  |
|   |                     |                 | “there”.                 |
+---+---------------------+-----------------+--------------------------+
| 5 | ``Not all results   | *Unchanged*     | The phrase is            |
|   | are flowers``       | (this is a      | intentional (“flowers”   |
|   |                     | playful phrase; | as a metaphor).          |
|   |                     | kept as‑is.)    |                          |
+---+---------------------+-----------------+--------------------------+
| 6 | ``although it       | ``although      | No change—just added the |
|   | caught several minor| it caught       | missing period at the    |
|   | issues there.``     |  several minor  | end for completeness.    |
|   |                     | issues there.`` |                          |
+---+---------------------+-----------------+--------------------------+
| 7 | ``Add the pertinent | ``Add the       | No spelling/grammar      |
|   | fixes, discard      | pertinent fixes,| issue; kept for clarity. |
|   | ing the bad ones.`` | discarding      |                          |
|   |                     | the bad ones.`` |                          |
+---+---------------------+-----------------+--------------------------+

Why these changes were made
---------------------------

  - Spelling – The text contained a handful of typographical errors 
    (excecuted, synatx). Fixing them prevents confusion and gives 
    the reader confidence in the quality of the documentation.  

  - Punctuation – Adding a period after the final sentence makes the
    paragraph a complete statement.  

  - Clarity – Adding a space between grammar and syntax keeps the 
    instruction legible.  

  - Professional tone – Corrected wording preserves the informal “flowers”
    metaphor while ensuring that the rest of the instruction reads cleanly.
</llm_output>

Not a bad review.

Funny enough, on (5) it understood my metaphor, but it ended replacing
it to "Not all results are perfect", probably to give a "professional
tone".

(**) Yeah, that prompt is grammatically incorrect: I should have used 
     "did you do?" but, as I'm playing with LLM, I like to write prompts
     with typos and other problems to see how well a 14B or less models
     would get it right :-D

     Sometimes I even change my language during prompts... it is funny
     that sometimes it follows my lead and change the language as well,
     while, on others, it keeps using the initial language... I even got
     a case were it randomly switched to a completely different language.
     
> The changes themselves look fine.

Good! want me to send a new version to improve description?

Thanks,
Mauro

Re: [PATCH v3 4/4] scripts/kernel-doc: some fixes to kernel-doc comments

[Mauro Carvalho Chehab]

Em Tue, 13 Jan 2026 22:49:43 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> Em Tue, 13 Jan 2026 13:55:18 -0700
> Jonathan Corbet <corbet@lwn.net> escreveu:
> 
> > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> >   

> > "flowers"?  Did the LLM put that out too? :)  

Heh, asking it to be funny and use figures of speech gave a funny
yet precise description:

<llm>
	There are hidden gremlins and linguistic shadows lurking in the
	kernel‑doc.py comments.
	Summon them with the aid of an LLM (gpt‑oss 14B), executed locally
	like a sorcerer’s spell, using this incantation:

	    review English grammar and syntax at the comments on the code below:
	    <cat scripts/kernel-doc.py>

	The oracle did not yield a bouquet of roses; instead, it revealed
	a handful of wilted blossoms. Gather the radiant ones, and toss
	the withered ones into the abyss.
</llm>

If you ever see a patch description like that from my side, you can 
be certain that it was a LLM-generated one ;-)


Thanks,
Mauro

OOT: some LLM-generated humor over a patch description - Was: Re: [PATCH v3 4/4] scripts/kernel-doc: some fixes to kernel-doc comments

[Mauro Carvalho Chehab]

Em Tue, 13 Jan 2026 23:10:36 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> Em Tue, 13 Jan 2026 22:49:43 +0100
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:
> 
> > Em Tue, 13 Jan 2026 13:55:18 -0700
> > Jonathan Corbet <corbet@lwn.net> escreveu:
> > 
> > > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> > >   
> 
> > > "flowers"?  Did the LLM put that out too? :)  
> 
> Heh, asking it to be funny and use figures of speech gave a funny
> yet precise description:

Heh, apparently I had nothing to do this night and decided to
see how LLM can play converting a patch description to something
different.

Feel free to Ignore this e-mail except if you're curious enough to see 
what can be produced on my local GPU.


---

Original patch description:

<description>
There are some typos and English errors at the kernel-doc.py comments.

Locate them with the help of LLM (gpt-oss 14B), locally excecuted
with this prompt:

    review English grammar andsyntax at the comments on the code
    below:
    <cat scripts/kernel-doc.py>

Not all results are flowers, although it caught several minor
issues there. Add the pertinent fixes, discarding the bad ones.
</description>

I asked gpt-oss to modify them to different styles, after those
initial prompts:

prompt 1: rewrite the text abusing with Figures of speech and being funny
prompt 2: write just the original text converted with metaphors. Place in a code block

(I placed already the results for it)

Then, I submitted some other prompts, asking to modify it to
several different styles:

1) The Fresh Prince of Bell-air
-------------------------------

Prompt: modify it to use “the fresh prince of bell-air” humor:

<llm>
	Yo, what's up? Look, there are some miss‑spelled words and grammar ghouls hiding in the kernel‑doc.py comments. 
	It's like my dad's closet—full of half‑forgotten stuff. 
	So let's roll up a fresh 14‑billion‑parameter LLM (think of it as the Fresh Prince's ride) and run it locally. 
	Tell it, “Check my grammar and syntax in the comments below, just like I check my reflection in the mirror.”

	    review English grammar and syntax at the comments on the code below:
	    <cat scripts/kernel-doc.py>

	The LLM didn't just spit out a rose‑filled bouquet; it found a few wilted flowers—some minor issues, no biggie. 
	Grab the good ones, toss the bad ones out, and keep the code as clean as a fresh pair of Jordans on the block. 
</llm>

2) Shakespearean style (LLM suggestion)
---------------------------------------

prompt: Could you rewrite the same message in a Shakespearean style instead of Fresh Prince?

<llm>
Hark! There be misspelt words and errant syntax lurking within the comments of kernel‑doc.py,
as if ghosts in a moonlit chamber.  
Summon then a mighty LLM (gpt‑oss 14B), as if a wizard of old, and run it anon upon the local realm,
with this solemn utterance:

    review English grammar and syntax at the comments on the code below:
    <cat scripts/kernel-doc.py>

The oracle returned no perfumed roses; it uncovered but a few wilted blooms—mere minor faults, indeed.
Gather the sweet ones, cast aside the withered, and let thy code shine as a polished shield beneath the sun.  
</llm>

3) for the the dress like a pirate day (LLM suggestion)
-------------------------------------------------------

prompt: Could you rewrite the message in a pirate‑literate style?

<llm>
Arrr, me hearties!  
Yar, there be misspelt words and bally syntax buried in the kernel‑doc.py comments – like doubloons in a sun‑baked chest.  
Summon ye a mighty LLM (gpt‑oss 14B), as stout as a kraken, and run it locally upon yer rigging with this command:  

    review English grammar and syntax at the comments on the code below:
    <cat scripts/kernel-doc.py>

The beast returned no fragrant roses, but spied a few wilted blooms – minor squalls, aye.  
Collect the gold, toss the rotten, and let yer code sail smooth as a polished hull.  
</llm>

4) noir detective (LLM suggestion)
----------------------------------

prompt: Can you rewrite the message in a noir detective style?

<llm>
I was staring at the back‑lit screen of kernel‑doc.py, the comments crawling like neon‑glowing alley cats.  
Something was off – misspelt words, syntax that smelled of bad coffee.  
I knew the only way to clean up the mess was to bring in the big guns.  

So I pulled out the LLM (gpt‑oss 14B), a private eye with a 14‑billion‑parameter brain, and set it to work right there in my office.  
With a cigarette in one hand and a keyboard in the other, I told the machine:  

    review English grammar and syntax at the comments on the code below:
    <cat scripts/kernel-doc.py>

The LLM didn't give me a bouquet of roses – it found a handful of wilted blooms, minor issues that could have turned the whole case sour.  
I snatched up the good ones, tossed the bad into the trash, and let the code breathe again, clean and sharp as a well‑sharpened revolver in a rain‑slick night.  
</llm>

5) Buffy the Vampire Slayer
---------------------------

by purpose, I used the wrong name on this TV series

prompt 1: what if it was part of buffy the vampire hunter script?
prompt 2: convert it into a description that buffy is doing to Angel about a past hunt


<llm>
**Buffy’s Tale of the “Kernel‑Doc” Hunt**

When Buffy approached Angel one night, her eyes still glittered with the after‑glow of a successful hunt. She leaned in, elbows on the battered wooden desk, and began to recount the latest battle—a hunt that, oddly enough, had started with a line of code rather than a silver stake.

“First thing I noticed,” she said, tapping her fingers against the monitor, “was that the victim’s lair—well, *kernel‑doc.py*—was littered with typo‑tombs and syntax‑slugs.” She paused, watching Angel’s skeptical gaze. “I mean, who writes code like that when they’re about to unleash a demon?”

Angel shifted, his winged silhouette casting a long shadow across the wall. “Did you just… fight a ghost in a file?”

Buffy smiled, a flash of mischievous humor in her voice. “Not a ghost, but a *vampire of the void*—the sort of entity that lingers in the shadows of poorly written scripts. I pulled out my trusty LLM, *gpt‑oss‑14B*, a 14‑billion‑parameter AI with a taste for order. I ran it locally, fed it the code with a simple prompt: “review English grammar and syntax at the comments on the code below,” and waited.”

She described how the AI combed through the comments like a detective sifting through evidence. “It wasn’t a bouquet of roses,” she laughed, “but it did flag a handful of minor glitches—those little syntax errors that could have turned a tidy codebase into a chaotic battlefield.”

Angel nodded, eyes widening as the picture painted itself. “So you used a language model to debug the demon’s lair?”

“Exactly,” Buffy confirmed. “I cherry‑picked the clean fixes, threw the corrupted ones out, and the code—our last line of defense—was restored to pristine condition. The demon didn’t stand a chance against an algorithmically flawless script.”

She paused, looking at Angel, her tone turning reflective. “That night, I realized that sometimes the real monsters we fight are the invisible ones in our systems. And with the right tools—human ingenuity and machine precision—you can patch up the weak spots before they’re exploited.”

Angel, ever the philosophical one, smiled. “So in the end, you saved the day by cleaning up a file instead of a coffin?”

Buffy grinned. “That’s one way to put it.”
</llm>

Thanks,
Mauro

Re: OOT: some LLM-generated humor over a patch description - Was: Re: [PATCH v3 4/4] scripts/kernel-doc: some fixes to kernel-doc comments

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> <llm>
> **Buffy’s Tale of the “Kernel‑Doc” Hunt**

I think it's a good thing I'm done for the day ... :)

jon

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

[Randy Dunlap]

On 1/13/26 9:19 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 | 26 +++++++++++++++++++-------
>  1 file changed, 19 insertions(+), 7 deletions(-)
> 
> diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
> index 7a1eaf986bcd..5d2f29e90ebe 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,21 @@ class MsgFormatter(logging.Formatter):
>          return logging.Formatter.format(self, record)
>  
>  def main():
> -    """Main program"""
> +    """
> +    Main program
> +    By default, the return value is:
> +
> +    - 0: parsing warnings or Python version is not compatible with
> +      kernel-doc. The rationale for the latter is to not break Linux
> +      compilation on such cases;

    Does "parsing warnings" mean that there were no errors, just possibly
    warnings or possibly nothing, i.e., all clean?

> +
> +    - 1: an abnormal condition happened;
> +
> +    - 2: arparse issued an error;

            argparse ?

> +
> +    - 3: -Werror is used, and one or more unfiltered parse warnings
> +         happened.
> +    """
>  
>      parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
>                                       description=DESC)
> @@ -323,16 +339,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__":

-- 
~Randy