docs: kdoc: some fixes to kernel-doc comments

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>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <ec08727f22ad35e6c58519c1f425f216f14b701c.1768823489.git.mchehab+huawei@kernel.org>

authored by

Mauro Carvalho Chehab and committed by

Jonathan Corbet 4 months ago 6cc45ee5 bd28e997

+13 -16

1 changed file

expand all

scripts

kernel-doc.py

+13 -16

scripts/kernel-doc.py

··· 9 9 # The rationale is that it shall fail gracefully during Kernel 10 10 # compilation with older Kernel versions. Due to that: 11 11 # - encoding line is needed here; 12 - # - no f-strings can be used on this file. 13 - # - the libraries that require newer versions can only be included 14 - # after Python version is checked. 12 + # - f-strings cannot be used in this file. 13 + # - libraries that require newer versions can only be included 14 + # after the Python version has been checked. 15 15 # 16 16 # Converted from the kernel-doc script originally written in Perl 17 17 # under GPLv2, copyrighted since 1998 by the following authors: ··· 88 88 # Yujie Liu <yujie.liu@intel.com> 89 89 90 90 """ 91 - kernel_doc 92 - ========== 93 - 94 - Print formatted kernel documentation to stdout 91 + Print formatted kernel documentation to stdout. 95 92 96 93 Read C language source or header FILEs, extract embedded 97 94 documentation comments, and print formatted documentation 98 95 to standard output. 99 96 100 - The documentation comments are identified by the "/**" 97 + The documentation comments are identified by the ``/**`` 101 98 opening comment mark. 102 99 103 100 See Documentation/doc-guide/kernel-doc.rst for the ··· 131 134 """ 132 135 133 136 EXPORT_DESC = """ 134 - Only output documentation for the symbols that have been 137 + Only output documentation for symbols that have been 135 138 exported using EXPORT_SYMBOL() and related macros in any input 136 139 FILE or -export-file FILE. 137 140 """ 138 141 139 142 INTERNAL_DESC = """ 140 - Only output documentation for the symbols that have NOT been 143 + Only output documentation for symbols that have NOT been 141 144 exported using EXPORT_SYMBOL() and related macros in any input 142 145 FILE or -export-file FILE. 143 146 """ ··· 160 163 """ 161 164 162 165 WARN_CONTENTS_BEFORE_SECTIONS_DESC = """ 163 - Warns if there are contents before sections (deprecated). 166 + Warn if there are contents before sections (deprecated). 164 167 165 168 This option is kept just for backward-compatibility, but it does nothing, 166 169 neither here nor at the original Perl script. ··· 168 171 169 172 170 173 class MsgFormatter(logging.Formatter): 171 - """Helper class to format warnings on a similar way to kernel-doc.pl""" 174 + """Helper class to format warnings in a similar way to kernel-doc.pl.""" 172 175 173 176 def format(self, record): 174 177 record.levelname = record.levelname.capitalize() ··· 270 273 help=NOSYMBOL_DESC) 271 274 272 275 parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections", 273 - action='store_true', help="Don't outputt DOC sections") 276 + action='store_true', help="Don't output DOC sections") 274 277 275 278 parser.add_argument("files", metavar="FILE", 276 279 nargs="+", help=FILES_DESC) ··· 299 302 python_ver = sys.version_info[:2] 300 303 if python_ver < (3,6): 301 304 # 302 - # Depending on Kernel configuration, kernel-doc --none is called at 305 + # Depending on the Kernel configuration, kernel-doc --none is called at 303 306 # build time. As we don't want to break compilation due to the 304 307 # usage of an old Python version, return 0 here. 305 308 # 306 309 if args.none: 307 - logger.error("Python 3.6 or later is required by kernel-doc. skipping checks") 310 + logger.error("Python 3.6 or later is required by kernel-doc. Skipping checks") 308 311 sys.exit(0) 309 312 310 313 sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.") ··· 313 316 logger.warning("Python 3.7 or later is required for correct results") 314 317 315 318 # 316 - # Import kernel-doc libraries only after checking Python version 319 + # Import kernel-doc libraries only after checking the Python version 317 320 # 318 321 from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415 319 322 from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415

Configure Feed

Configure Feed