[PATCH 0/2] docs: kdoc: print each warning once, and only for selected symbols

[PATCH 0/2] docs: kdoc: print each warning once, and only for selected symbols

[Prateekshit Jaiswal via B4 Relay]

kernel-doc currently prints every documented symbol's warnings twice.
With -function or -export it also warns about symbols that were not
asked for. Both come from the parser flushing warnings of entries it
mistakenly treats as discarded; patch 2 stops that.

Doing only that would uncover an older bug: the output step never
prints warnings for symbols selected with -function or -export.
Patch 1 restores those first, so nothing is lost at any point in the
series.

Testing:
- tools/unittests/run.py passes after each patch. Without patch 1,
  the new OutputFilterWarnings tests for selected and exported symbols
  fail; without patch 2, test_stored_entry fails.
- Warnings printed for intel_dkl_phy.c, before and after the series:
  -Wall: 2 and 1; -function intel_dkl_phy_read: 1 and 1;
  -function intel_dkl_phy_write: 1 and 0;
  -nosymbol intel_dkl_phy_read: 1 and 0.
- kernel-doc -none -Wall over the 10320 .c and .h files with kernel-doc
  comments: 87900 and 49625 output lines, with the same 48026 distinct
  lines.
- The two "Excess struct member" warnings for page_pool_params, which
  Documentation/networking/page_pool.rst pulls in with :identifiers:,
  are still printed, once each.

Notes:
- The new tests patch config.warning directly. MockKdocConfig.warning()
  is never called, because KdocConfig.__init__() sets self.warning as
  an instance attribute that shadows it, so the MockLogging handler
  does not see config.warning() messages. I can send a separate fix for
  that.
- Plain --yaml output never printed warnings itself, so with patch 2
  it no longer shows the warnings of stored entries. With -rst or -man
  they are still printed, once, by the embedded output formats.

---
Prateekshit Jaiswal (2):
      docs: kdoc: emit warnings for symbols selected with -function/-export
      docs: kdoc: don't print warnings of stored entries twice

 tools/lib/python/kdoc/kdoc_output.py |   1 +
 tools/lib/python/kdoc/kdoc_parser.py |   4 +-
 tools/unittests/test_kdoc_parser.py  | 126 +++++++++++++++++++++++++++++++++++
 3 files changed, 130 insertions(+), 1 deletion(-)
---
base-commit: 2138148bf44fd84d3e0a863f0e8cb3627cdcc606
change-id: 20261114-kdoc-dup-warnings-785f4a72b806

Best regards,
-- 
Prateekshit Jaiswal <prateekshitjaiswal73@gmail.com>

[PATCH 1/2] docs: kdoc: emit warnings for symbols selected with -function/-export

[Prateekshit Jaiswal via B4 Relay]

From: Prateekshit Jaiswal <prateekshitjaiswal73@gmail.com>

Commit 9cbc2d3b137b ("scripts/kernel-doc.py: postpone warnings to the
output plugin") moved warning output into
OutputFormat.check_declaration(), which is supposed to print the
warnings of each symbol it lets through. The OUTPUT_INCLUDE and
OUTPUT_EXPORTED branch returns without that call, so -function,
-export, and the Sphinx kernel-doc :identifiers: and :export: options
drop the warnings of the symbols they keep. On v6.18 the command below
prints nothing, even though intel_dkl_phy_read() does not describe its
return value:

  $ ./scripts/kernel-doc -none -Wall -function intel_dkl_phy_read drivers/gpu/drm/i915/display/intel_dkl_phy.c

From v6.19 the warning still appears, because the parser prints the
warnings of every entry itself. That is a separate bug, fixed in the
next patch. Fixing only that one would make this gap visible again.
Until then, this change prints the selected symbols' warnings twice in
these modes.

Call out_warnings() in that branch as well, as the other modes do, and
add tests for the warnings shown with each output filter.

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: 9cbc2d3b137b ("scripts/kernel-doc.py: postpone warnings to the output plugin")
Signed-off-by: Prateekshit Jaiswal <prateekshitjaiswal73@gmail.com>
---
 tools/lib/python/kdoc/kdoc_output.py |  1 +
 tools/unittests/test_kdoc_parser.py  | 71 ++++++++++++++++++++++++++++++++++++
 2 files changed, 72 insertions(+)

diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/kdoc_output.py
index 659a2c6fb6be..e0f24302cbc4 100644
--- a/tools/lib/python/kdoc/kdoc_output.py
+++ b/tools/lib/python/kdoc/kdoc_output.py
@@ -167,6 +167,7 @@ class OutputFormat:
 
         if self.out_mode in [self.OUTPUT_INCLUDE, self.OUTPUT_EXPORTED]:
             if name in self.function_table:
+                self.out_warnings(args)
                 return True
 
         if self.out_mode == self.OUTPUT_INTERNAL:
diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdoc_parser.py
index 6e305988cb6d..35f7a140942d 100755
--- a/tools/unittests/test_kdoc_parser.py
+++ b/tools/unittests/test_kdoc_parser.py
@@ -353,6 +353,77 @@ class ManFilterTail(unittest.TestCase):
         self.assertEqual(self.run_filter(export=True), "")
 
 
+class OutputFilterWarnings(unittest.TestCase):
+    """
+    The output step shows the warnings of the symbols it outputs, once.
+    """
+
+    source = dedent("""
+        /**
+         * foo - First function
+         */
+        int foo(int a) { return 0; };
+
+        /**
+         * bar - Second function
+         * @b: an argument
+         */
+        int bar(int b) { return 0; };
+    """)
+
+    def setUp(self):
+        self.config = MockKdocConfig()
+        kernel_doc = KernelDoc(self.config, "mock.c", CTransforms())
+
+        with patch('builtins.open', new_callable=mock_open,
+                   read_data=self.source):
+            with patch.object(self.config, 'warning'):
+                _, self.entries = kernel_doc.parse_kdoc()
+
+        self.out_style = ManFormat()
+        self.out_style.set_config(self.config)
+
+    def run_filter(self, **kwargs):
+        args = {"export": False, "internal": False, "symbol": None,
+                "nosymbol": None, "function_table": set(),
+                "enable_lineno": False, "no_doc_sections": False}
+        args.update(kwargs)
+
+        self.out_style.set_filter(**args)
+
+        with patch.object(self.config, 'warning') as warning:
+            self.out_style.output_symbols("mock.c", self.entries)
+
+        return [call.args[0] for call in warning.call_args_list]
+
+    def test_all_symbols(self):
+        """Without a filter, the warning of foo is shown."""
+        warnings = self.run_filter()
+
+        self.assertEqual(len(warnings), 1)
+        self.assertIn("'a' not described in 'foo'", warnings[0])
+
+    def test_selected_symbol(self):
+        """The warning of a symbol selected by name is shown."""
+        warnings = self.run_filter(symbol=["foo"], function_table={"foo"})
+
+        self.assertEqual(len(warnings), 1)
+        self.assertIn("'a' not described in 'foo'", warnings[0])
+
+    def test_exported_symbol(self):
+        """The warning of an exported symbol is shown."""
+        warnings = self.run_filter(export=True, function_table={"foo"})
+
+        self.assertEqual(len(warnings), 1)
+        self.assertIn("'a' not described in 'foo'", warnings[0])
+
+    def test_other_symbol(self):
+        """The warning of a symbol that is not selected is not shown."""
+        warnings = self.run_filter(symbol=["bar"], function_table={"bar"})
+
+        self.assertEqual(warnings, [])
+
+
 class CToRest(unittest.TestCase):
     out_style = RestFormat()
     config = MockKdocConfig()

-- 
2.53.0

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

[Prateekshit Jaiswal via B4 Relay]

From: Prateekshit Jaiswal <prateekshitjaiswal73@gmail.com>

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@gmail.com>
---
 tools/lib/python/kdoc/kdoc_parser.py |  4 ++-
 tools/unittests/test_kdoc_parser.py  | 55 ++++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index 80d4245acd17..ef5879b05308 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -135,6 +135,7 @@ class KernelEntry:
         self.prototype = ""
 
         self.warnings = []
+        self.stored = False
 
         self.parameterlist = []
         self.parameterdescs = {}
@@ -323,6 +324,7 @@ class KernelDoc:
                         self.entry.parametertypes,
                         self.entry.parameterdesc_start_lines)
         self.entries.append(item)
+        self.entry.stored = True
 
         self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
 
@@ -346,7 +348,7 @@ class KernelDoc:
               during the output step of the code, depending on the
               selected symbols.
         """
-        if self.entry and self.entry not in self.entries:
+        if self.entry and not self.entry.stored:
             for log_msg in self.entry.warnings:
                 self.config.warning(log_msg)
 
diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdoc_parser.py
index 35f7a140942d..709455a4b39c 100755
--- a/tools/unittests/test_kdoc_parser.py
+++ b/tools/unittests/test_kdoc_parser.py
@@ -567,6 +567,61 @@ class TestContextLockStruct(GenerateKdocItem):
         self.assertEqual(entries[0].name, "debugfs_cancellation")
         self.assertEqual(entries[0].warnings, [])
 
+class TestUnusedWarnings(GenerateKdocItem):
+    """
+    Test that the parser itself only emits warnings of discarded entries.
+    """
+
+    def parse(self, source):
+        """
+        Parse source, returning the entries and the warnings emitted.
+        """
+        kernel_doc = KernelDoc(self.config, "test.c", self.xforms)
+
+        with patch('builtins.open', new_callable=mock_open,
+                   read_data=dedent(source)):
+            with patch.object(self.config, 'warning') as warning:
+                _, entries = kernel_doc.parse_kdoc()
+
+        return entries, [call.args[0] for call in warning.call_args_list]
+
+    def test_stored_entry(self):
+        """
+        Warnings of a stored entry are left for the output step, which
+        applies the symbol filters, so they must not be emitted here.
+        """
+        source = """
+            /**
+             * func - Do nothing
+             */
+            int func(int arg) { return 0; }
+        """
+
+        entries, emitted = self.parse(source)
+
+        self.assertEqual(len(entries), 1)
+        self.assertEqual(len(entries[0].warnings), 1)
+        self.assertIn("'arg' not described", entries[0].warnings[0])
+        self.assertEqual(emitted, [])
+
+    def test_discarded_entry(self):
+        """
+        Warnings of an entry that is never stored are emitted once.
+        """
+        source = """
+            /**
+             * to_user_ptr - cast a u64 to a user space pointer
+             * @x: the u64 to convert
+             */
+            #define u64_to_user_ptr(x) ((void __user *)(uintptr_t)(x))
+        """
+
+        entries, emitted = self.parse(source)
+
+        self.assertEqual(entries, [])
+        self.assertEqual(len(emitted), 1)
+        self.assertIn("expecting prototype for to_user_ptr()", emitted[0])
+
 #
 # Class and logic to create dynamic tests from YAML
 #

-- 
2.53.0

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

[Randy Dunlap]

On 11/13/26 10:14 PM, Prateekshit Jaiswal via B4 Relay wrote:
> From: Prateekshit Jaiswal <prateekshitjaiswal73@gmail.com>
> 
> 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@gmail.com>

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

Tested-by: Randy Dunlap <rdunlap@infradead.org>

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