[PATCH v4 0/4] fix -Werror issues

[PATCH v4 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.

---

v4:
  - improved description on patch 4;
  - fixed some typos and problems at patch2 comments;
  - fixed a potential sphinx.ext.autodoc issue.

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                | 73 ++++++++++++++++++----------
 tools/lib/python/kdoc/kdoc_parser.py | 31 +++++++++---
 2 files changed, 73 insertions(+), 31 deletions(-)

-- 
2.52.0

[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

[PATCH v4 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 3992ca49d593..1d6036265c0d 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:
 #
@@ -196,8 +196,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.")
 
@@ -212,8 +213,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.")
 
@@ -234,8 +236,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()
@@ -247,8 +250,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()
 
@@ -261,7 +265,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)
 
@@ -294,9 +300,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)
@@ -306,7 +314,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
 
@@ -345,6 +355,8 @@ def main():
 
     sys.exit(0)
 
+#
 # Call main method
+#
 if __name__ == "__main__":
     main()
-- 
2.52.0

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

[Mauro Carvalho Chehab]

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>

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

-

While here, replace:

    "/**" with: ``/**``

As, if we ever rename this script to kernel_doc.py and add it to
Sphinx ext autodoc, we want to avoid this warning:

    scripts/kernel_doc.py:docstring of kernel_doc:10: WARNING: Inline strong start-string without end-string. [docutils]

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

diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index 1d6036265c0d..7f84c58f7dc4 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:
@@ -97,7 +97,7 @@ Read C language source or header FILEs, extract embedded
 documentation comments, and print formatted documentation
 to standard output.
 
-The documentation comments are identified by the "/**"
+The documentation comments are identified by the ``/**``
 opening comment mark.
 
 See Documentation/doc-guide/kernel-doc.rst for the
@@ -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()
@@ -272,7 +272,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)
@@ -301,12 +301,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.")
@@ -315,7 +315,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 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