Re: [PATCH 2/2] docs: kdoc: don't print warnings of stored entries twice

From: Randy Dunlap

Date: Sat Nov 14 2026 - 15:18:11 EST




On 11/13/26 10:14 PM, Prateekshit Jaiswal via B4 Relay wrote:
> From: Prateekshit Jaiswal <prateekshitjaiswal73@xxxxxxxxx>
>
> Commit 469c1c9eb6c9 ("kernel-doc: Issue warnings that were silently
> discarded") was meant to print warnings of entries that never reach
> the output step. With no symbol filter, kernel-doc now prints the
> warnings of every documented symbol twice:
>
> $ ./scripts/kernel-doc -none -Wall drivers/gpu/drm/i915/display/intel_dkl_phy.c
> Warning: drivers/gpu/drm/i915/display/intel_dkl_phy.c:47 No description found for return value of 'intel_dkl_phy_read'
> Warning: drivers/gpu/drm/i915/display/intel_dkl_phy.c:47 No description found for return value of 'intel_dkl_phy_read'
>
> The flush uses "self.entry not in self.entries" to tell stored entries
> from discarded ones. output_declaration() stores a new KdocItem built
> from the entry, never the KernelEntry itself, so that test is always
> true. Every stored entry then warns once in the parser and once in the
> output plugin.
>
> Those parser-side prints also ignore the later symbol filter, so
> "-function intel_dkl_phy_write" still warns about intel_dkl_phy_read().
> Commit 292eca316321 ("docs: kdoc: fix logic to handle unissued
> warnings") routes the flush through config.warning(), which increments
> the warning count. -Werror then reports "2 warnings as errors" for a
> single warning, and a -function run fails because of a different
> symbol.
>
> Mark the entry as stored in output_declaration(), flush warnings only
> for entries that were not stored, and add tests for both cases. This
> needs the previous patch. Without it, symbols selected with -function
> or -export would lose their warnings.
>
> Running "kernel-doc -none -Wall" over the 10320 .c and .h files with
> kernel-doc comments, the output shrinks from 87900 to 49625 lines,
> while the set of distinct lines stays the same.
>
> The problem was found, and the fix and tests drafted, with the help of
> an AI coding assistant (Claude Code); I have reviewed and tested the
> result.
>
> Fixes: 469c1c9eb6c9 ("kernel-doc: Issue warnings that were silently discarded")
> Signed-off-by: Prateekshit Jaiswal <prateekshitjaiswal73@xxxxxxxxx>

Thank you very much. I had complained about this issue.

Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>

This reduces a full "make W=1 mandocs" from 31341 lines down to
21373 lines. That eliminates a LOT of noise/duplication when
reviewing/looking at warnings.

> ---
> tools/lib/python/kdoc/kdoc_parser.py | 4 ++-
> tools/unittests/test_kdoc_parser.py | 55 ++++++++++++++++++++++++++++++++++++
> 2 files changed, 58 insertions(+), 1 deletion(-)

--
~Randy