Commit 292eca31 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

docs: kdoc: fix logic to handle unissued warnings 

Changeset 469c1c9e ("kernel-doc: Issue warnings that were silently discarded")
didn't properly addressed the missing messages behavior, as
it was calling directly python logger low-level function,
instead of using the expected method to emit warnings.

Basically, there are two methods to log messages:

- self.config.log.warning() - This is the raw level to emit a
  warning. It just writes the a message at stderr, via python
  logging, as it is initialized as:

    self.config.log = logging.getLogger("kernel-doc")

- self.config.warning() - This is where we actually consider a
  message as a warning, properly incrementing error count.

Due to that, several parsing error messages are internally considered
as success, causing -Werror to not work on such messages.

While here, ensure that the last ignored entry will also be handled
by adding an extra check at the end of the parse handler.

Fixes: 469c1c9e ("kernel-doc: Issue warnings that were silently discarded")
Closes: https://lore.kernel.org/linux-doc/20260112091053.00cee29a@foz.lan/


Cc: stable@vger.kernel.org
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: default avatarAndy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Message-ID: <95109a6585171da4d6900049deaa2634b41ee743.1768823489.git.mchehab+huawei@kernel.org>
parent 20f73d6f

tools/lib/python/kdoc/kdoc_parser.py

+28 −7
Original line number Diff line number Diff line
@@ -295,7 +295,7 @@ class KernelEntry: 


    # TODO: rename to emit_message after removal of kernel-doc.pl

    def emit_msg(self, ln, msg, *, warning=True):

        """Emit a message"""

        """Emit a message."""



        log_msg = f"{self.fname}:{ln} {msg}"
@@ -448,18 +448,37 @@ class KernelDoc: 


        self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))



    def emit_unused_warnings(self):

        """

        When the parser fails to produce a valid entry, it places some

        warnings under `entry.warnings` that will be discarded when resetting

        the state.



        Ensure that those warnings are not lost.



        .. note::



              Because we are calling `config.warning()` here, those

              warnings are not filtered by the `-W` parameters: they will all

              be produced even when `-Wreturn`, `-Wshort-desc`, and/or

              `-Wcontents-before-sections` are used.



              Allowing those warnings to be filtered is complex, because it

              would require storing them in a buffer and then filtering them

              during the output step of the code, depending on the

              selected symbols.

        """

        if self.entry and self.entry not in self.entries:

            for log_msg in self.entry.warnings:

                self.config.warning(log_msg)



    def reset_state(self, ln):

        """

        Ancillary routine to create a new entry. It initializes all

        variables used by the state machine.

        """



        #

        # Flush the warnings out before we proceed further

        #

        if self.entry and self.entry not in self.entries:

            for log_msg in self.entry.warnings:

                self.config.log.warning(log_msg)

        self.emit_unused_warnings()



        self.entry = KernelEntry(self.config, self.fname, ln)
@@ -1741,6 +1760,8 @@ class KernelDoc: 
                        # Hand this line to the appropriate state handler

                        self.state_actions[self.state](self, ln, line)



            self.emit_unused_warnings()



        except OSError:

            self.config.log.error(f"Error: Cannot open file {self.fname}")