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

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <228d7af7534816416b574e17624e58285d57ef6f@intel.com>
Date: Mon, 12 Jan 2026 14:11:47 +0200
From: Jani Nikula <jani.nikula@...el.com>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>, Linux Doc Mailing
 List <linux-doc@...r.kernel.org>, Mauro Carvalho Chehab
 <mchehab@...nel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
 linux-kernel@...r.kernel.org, Jonathan Corbet <corbet@....net>
Subject: Re: [PATCH 4/4] scripts/kernel-doc: some fixes to kernel-doc comments

On Mon, 12 Jan 2026, Mauro Carvalho Chehab <mchehab+huawei@...nel.org> wrote:
> 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@...nel.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 bcb60136fc9c..5086248ee532 100755
> --- a/scripts/kernel-doc.py
> +++ b/scripts/kernel-doc.py
> @@ -9,10 +9,10 @@
>  #       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:
>  #
> @@ -132,13 +132,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.
>  """
> @@ -161,7 +161,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.
> @@ -169,7 +169,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()
> @@ -268,7 +268,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)
> @@ -297,12 +297,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")

Please don't add silly non-breaking space in there.

>              sys.exit(0)
>  
>          sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.")
> @@ -311,7 +311,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

-- 
Jani Nikula, Intel