tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

docs: kdoc: fix logic to handle unissued warnings

Changeset 469c1c9eb6c9 ("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: 469c1c9eb6c9 ("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: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <95109a6585171da4d6900049deaa2634b41ee743.1768823489.git.mchehab+huawei@kernel.org>

authored by

Mauro Carvalho Chehab and committed by
Jonathan Corbet 292eca31 20f73d6f

+28 -7
+28 -7
tools/lib/python/kdoc/kdoc_parser.py
··· 295 295 296 296 # TODO: rename to emit_message after removal of kernel-doc.pl 297 297 def emit_msg(self, ln, msg, *, warning=True): 298 - """Emit a message""" 298 + """Emit a message.""" 299 299 300 300 log_msg = f"{self.fname}:{ln} {msg}" 301 301 ··· 448 448 449 449 self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args)) 450 450 451 + def emit_unused_warnings(self): 452 + """ 453 + When the parser fails to produce a valid entry, it places some 454 + warnings under `entry.warnings` that will be discarded when resetting 455 + the state. 456 + 457 + Ensure that those warnings are not lost. 458 + 459 + .. note:: 460 + 461 + Because we are calling `config.warning()` here, those 462 + warnings are not filtered by the `-W` parameters: they will all 463 + be produced even when `-Wreturn`, `-Wshort-desc`, and/or 464 + `-Wcontents-before-sections` are used. 465 + 466 + Allowing those warnings to be filtered is complex, because it 467 + would require storing them in a buffer and then filtering them 468 + during the output step of the code, depending on the 469 + selected symbols. 470 + """ 471 + if self.entry and self.entry not in self.entries: 472 + for log_msg in self.entry.warnings: 473 + self.config.warning(log_msg) 474 + 451 475 def reset_state(self, ln): 452 476 """ 453 477 Ancillary routine to create a new entry. It initializes all 454 478 variables used by the state machine. 455 479 """ 456 480 457 - # 458 - # Flush the warnings out before we proceed further 459 - # 460 - if self.entry and self.entry not in self.entries: 461 - for log_msg in self.entry.warnings: 462 - self.config.log.warning(log_msg) 481 + self.emit_unused_warnings() 463 482 464 483 self.entry = KernelEntry(self.config, self.fname, ln) 465 484 ··· 1759 1740 not self.process_export(export_table, line): 1760 1741 # Hand this line to the appropriate state handler 1761 1742 self.state_actions[self.state](self, ln, line) 1743 + 1744 + self.emit_unused_warnings() 1762 1745 1763 1746 except OSError: 1764 1747 self.config.log.error(f"Error: Cannot open file {self.fname}")