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]
Unified · Split
| @@ -9,9 +9,9 @@ · 8 unmodified lines | ||
| 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,16 +88,13 @@ · 70 unmodified lines | ||
| 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 |
| @@ -134,13 +131,13 @@ May be used multiple times. · 30 unmodified lines | ||
| 134 | 131 | """ |
| 135 | 132 | |
| 136 | 133 | EXPORT_DESC = """ |
| 137 | −Only output documentation for the symbols that have been | |
| 134 | +Only output documentation for symbols that have been | |
| 138 | 135 | exported using EXPORT_SYMBOL() and related macros in any input |
| 139 | 136 | FILE or -export-file FILE. |
| 140 | 137 | """ |
| 141 | 138 | |
| 142 | 139 | INTERNAL_DESC = """ |
| 143 | −Only output documentation for the symbols that have NOT been | |
| 140 | +Only output documentation for symbols that have NOT been | |
| 144 | 141 | exported using EXPORT_SYMBOL() and related macros in any input |
| 145 | 142 | FILE or -export-file FILE. |
| 146 | 143 | """ |
| @@ -163,7 +160,7 @@ Header and C source files to be parsed. · 16 unmodified lines | ||
| 163 | 160 | """ |
| 164 | 161 | |
| 165 | 162 | WARN_CONTENTS_BEFORE_SECTIONS_DESC = """ |
| 166 | −Warns if there are contents before sections (deprecated). | |
| 163 | +Warn if there are contents before sections (deprecated). | |
| 167 | 164 | |
| 168 | 165 | This option is kept just for backward-compatibility, but it does nothing, |
| 169 | 166 | neither here nor at the original Perl script. |
| @@ -171,7 +168,7 @@ neither here nor at the original Perl script. · 1 unmodified line | ||
| 171 | 168 | |
| 172 | 169 | |
| 173 | 170 | class MsgFormatter(logging.Formatter): |
| 174 | − """Helper class to format warnings on a similar way to kernel-doc.pl""" | |
| 171 | + """Helper class to format warnings in a similar way to kernel-doc.pl.""" | |
| 175 | 172 | |
| 176 | 173 | def format(self, record): |
| 177 | 174 | record.levelname = record.levelname.capitalize() |
| @@ -273,7 +270,7 @@ def main(): · 95 unmodified lines | ||
| 273 | 270 | help=NOSYMBOL_DESC) |
| 274 | 271 | |
| 275 | 272 | parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections", |
| 276 | − action='store_true', help="Don't outputt DOC sections") | |
| 273 | + action='store_true', help="Don't output DOC sections") | |
| 277 | 274 | |
| 278 | 275 | parser.add_argument("files", metavar="FILE", |
| 279 | 276 | nargs="+", help=FILES_DESC) |
| @@ -302,12 +299,12 @@ def main(): · 22 unmodified lines | ||
| 302 | 299 | python_ver = sys.version_info[:2] |
| 303 | 300 | if python_ver < (3,6): |
| 304 | 301 | # |
| 305 | − # Depending on Kernel configuration, kernel-doc --none is called at | |
| 302 | + # Depending on the Kernel configuration, kernel-doc --none is called at | |
| 306 | 303 | # build time. As we don't want to break compilation due to the |
| 307 | 304 | # usage of an old Python version, return 0 here. |
| 308 | 305 | # |
| 309 | 306 | if args.none: |
| 310 | − logger.error("Python 3.6 or later is required by kernel-doc. skipping checks") | |
| 307 | + logger.error("Python 3.6 or later is required by kernel-doc. Skipping checks") | |
| 311 | 308 | sys.exit(0) |
| 312 | 309 | |
| 313 | 310 | sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.") |
| @@ -316,7 +313,7 @@ def main(): · 2 unmodified lines | ||
| 316 | 313 | logger.warning("Python 3.7 or later is required for correct results") |
| 317 | 314 | |
| 318 | 315 | # |
| 319 | − # Import kernel-doc libraries only after checking Python version | |
| 316 | + # Import kernel-doc libraries only after checking the Python version | |
| 320 | 317 | # |
| 321 | 318 | from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415 |
| 322 | 319 | from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415 |