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

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

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

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