Commit 9cbc2d3b authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

scripts/kernel-doc.py: postpone warnings to the output plugin 



We don't want to have warnings displayed for symbols that
weren't output. So, postpone warnings print to the output
plugin, where symbol output is validated.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/e6344711e390cf22af02a56bb5dd51ca67c0afb6.1744106242.git.mchehab+huawei@kernel.org
parent 9235ec5e

scripts/lib/kdoc/kdoc_output.py

+19 −5
Original line number Diff line number Diff line
@@ -116,7 +116,16 @@ class OutputFormat: 


        return block



    def check_doc(self, name):

    def out_warnings(self, args):

        warnings = args.get('warnings', [])



        for warning, log_msg in warnings:

            if warning:

                self.config.log.warning(log_msg)

            else:

                self.config.log.info(log_msg)



    def check_doc(self, name, args):

        """Check if DOC should be output"""



        if self.no_doc_sections:
@@ -126,19 +135,22 @@ class OutputFormat: 
            return False



        if self.out_mode == self.OUTPUT_ALL:

            self.out_warnings(args)

            return True



        if self.out_mode == self.OUTPUT_INCLUDE:

            if name in self.function_table:

                self.out_warnings(args)

                return True



        return False



    def check_declaration(self, dtype, name):

    def check_declaration(self, dtype, name, args):

        if name in self.nosymbol:

            return False



        if self.out_mode == self.OUTPUT_ALL:

            self.out_warnings(args)

            return True



        if self.out_mode in [self.OUTPUT_INCLUDE, self.OUTPUT_EXPORTED]:
@@ -147,9 +159,11 @@ class OutputFormat: 


        if self.out_mode == self.OUTPUT_INTERNAL:

            if dtype != "function":

                self.out_warnings(args)

                return True



            if name not in self.function_table:

                self.out_warnings(args)

                return True



        return False
@@ -163,7 +177,7 @@ class OutputFormat: 
            self.out_doc(fname, name, args)

            return self.data



        if not self.check_declaration(dtype, name):

        if not self.check_declaration(dtype, name, args):

            return self.data



        if dtype == "function":
@@ -328,7 +342,7 @@ class RestFormat(OutputFormat): 
        self.data += "\n"



    def out_doc(self, fname, name, args):

        if not self.check_doc(name):

        if not self.check_doc(name, args):

            return

        self.out_section(args, out_docblock=True)
@@ -586,7 +600,7 @@ class ManFormat(OutputFormat): 
        sectionlist = args.get('sectionlist', [])

        sections = args.get('sections', {})



        if not self.check_doc(name):

        if not self.check_doc(name, args):

                return



        self.data += f'.TH "{module}" 9 "{module}" "{self.man_date}" "API Manual" LINUX' + "\n"

scripts/lib/kdoc/kdoc_parser.py

+20 −21
Original line number Diff line number Diff line
@@ -131,23 +131,23 @@ class KernelDoc: 
        # Place all potential outputs into an array

        self.entries = []



    def show_warnings(self, dtype, declaration_name):  # pylint: disable=W0613

        """

        Allow filtering out warnings

        """



        # TODO: implement it



        return True



    # TODO: rename to emit_message

    def emit_warning(self, ln, msg, warning=True):

        """Emit a message"""



        log_msg = f"{self.fname}:{ln} {msg}"



        if self.entry:

            # Delegate warning output to output logic, as this way it

            # will report warnings/info only for symbols that are output



            self.entry.warnings.append((warning, log_msg))

            return



        if warning:

            self.config.log.warning("%s:%d %s", self.fname, ln, msg)

            self.config.log.warning(log_msg)

        else:

            self.config.log.info("%s:%d %s", self.fname, ln, msg)

            self.config.log.info(log_msg)



    def dump_section(self, start_new=True):

        """
@@ -221,10 +221,9 @@ class KernelDoc: 
        # For now, we're keeping the same name of the function just to make

        # easier to compare the source code of both scripts



        if "declaration_start_line" not in args:

        args["declaration_start_line"] = self.entry.declaration_start_line



        args["type"] = dtype

        args["warnings"] = self.entry.warnings



        # TODO: use colletions.OrderedDict
@@ -257,6 +256,8 @@ class KernelDoc: 
        self.entry.struct_actual = ""

        self.entry.prototype = ""



        self.entry.warnings = []



        self.entry.parameterlist = []

        self.entry.parameterdescs = {}

        self.entry.parametertypes = {}
@@ -328,7 +329,7 @@ class KernelDoc: 
        if param not in self.entry.parameterdescs and not param.startswith("#"):

            self.entry.parameterdescs[param] = self.undescribed



            if self.show_warnings(dtype, declaration_name) and "." not in param:

            if "." not in param:

                if decl_type == 'function':

                    dname = f"{decl_type} parameter"

                else:
@@ -868,14 +869,12 @@ class KernelDoc: 
            self.entry.parameterlist.append(arg)

            if arg not in self.entry.parameterdescs:

                self.entry.parameterdescs[arg] = self.undescribed

                if self.show_warnings("enum", declaration_name):

                self.emit_warning(ln,

                                  f"Enum value '{arg}' not described in enum '{declaration_name}'")

            member_set.add(arg)



        for k in self.entry.parameterdescs:

            if k not in member_set:

                if self.show_warnings("enum", declaration_name):

                self.emit_warning(ln,

                                  f"Excess enum value '%{k}' description in '{declaration_name}'")