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 <[email protected]>
---
scripts/kernel-doc.py | 29 +++++++++++++----------------
1 file changed, 13 insertions(+), 16 deletions(-)
diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index f1f3f56edeb5..4e3b9cfe3fd7 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:
@@ -88,16 +88,13 @@
# Yujie Liu <[email protected]>
"""
-kernel_doc
-==========
-
-Print formatted kernel documentation to stdout
+Print formatted kernel documentation to stdout.
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 +131,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 +160,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 +168,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 +270,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 +299,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 +313,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
