Commit 6cc45ee5 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Message-ID: <ec08727f22ad35e6c58519c1f425f216f14b701c.1768823489.git.mchehab+huawei@kernel.org>
parent bd28e997

scripts/kernel-doc.py

+13 −16
Original line number Diff line number Diff line
@@ -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 <yujie.liu@intel.com>



"""

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