[PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Andy Shevchenko]

When kernel-doc parses the sections for the documentation some errors
may occur. In many cases the warning is simply stored to the current
"entry" object. However, in the most of such cases this object gets
discarded and there is no way for the output engine to even know about
that. To avoid that, check if the "entry" is going to be discarded and
if there warnings have been collected, issue them to the current logger
as is and then flush the "entry". This fixes the problem that original
Perl implementation doesn't have.

As of Linux kernel v6.18-rc4 the reproducer can be:

$ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h
...
Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr
...

while with the proposed change applied it gives one more line:

$ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h
...
Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr
Warning: include/linux/util_macros.h:144 expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead
...

And with the original Perl script:

$ scripts/kernel-doc.pl -v -none -Wall include/linux/util_macros.h
...
include/linux/util_macros.h:139: info: Scanning doc for function to_user_ptr
include/linux/util_macros.h:149: warning: expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead
...

Fixes: 9cbc2d3b137b ("scripts/kernel-doc.py: postpone warnings to the output plugin")
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
 scripts/lib/kdoc/kdoc_parser.py | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index ee1a4ea6e725..f7dbb0868367 100644
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -451,6 +451,13 @@ class KernelDoc:
         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.entry = KernelEntry(self.config, self.fname, ln)
 
         # State flags
-- 
2.50.1

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[kernel test robot]

Hi Andy,

kernel test robot noticed the following build warnings:

[auto build test WARNING on lwn/docs-next]
[also build test WARNING on next-20251104]
[cannot apply to linus/master v6.18-rc4]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Andy-Shevchenko/kernel-doc-Issue-warnings-that-were-silently-discarded/20251105-055629
base:   git://git.lwn.net/linux.git docs-next
patch link:    https://lore.kernel.org/r/20251104215502.1049817-1-andriy.shevchenko%40linux.intel.com
patch subject: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded
config: openrisc-allnoconfig (https://download.01.org/0day-ci/archive/20251105/202511050720.nJ9ccENC-lkp@intel.com/config)
compiler: or1k-linux-gcc (GCC) 15.1.0
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20251105/202511050720.nJ9ccENC-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202511050720.nJ9ccENC-lkp@intel.com/

All warnings (new ones prefixed by >>):

>> Warning: block/blk-mq-dma.c:374 expecting prototype for blk_rq_integrity_dma_map_iter_start(). Prototype was for blk_rq_integrity_dma_map_iter_next() instead
--
>> Warning: kernel/nstree.c:215 function parameter 'ns_tree' not described in '__ns_tree_adjoined_rcu'
>> Warning: kernel/nstree.c:215 expecting prototype for ns_tree_adjoined_rcu(). Prototype was for __ns_tree_adjoined_rcu() instead
--
>> Warning: lib/hweight.c:13 function parameter 'w' not described in '__sw_hweight32'
>> Warning: lib/hweight.c:13 expecting prototype for hweightN(). Prototype was for __sw_hweight32() instead
--
>> Warning: mm/vmalloc.c:4129 expecting prototype for vrealloc_node_align_noprof(). Prototype was for vrealloc_node_align() instead

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[kernel test robot]

Hi Andy,

kernel test robot noticed the following build warnings:

[auto build test WARNING on lwn/docs-next]
[also build test WARNING on next-20251104]
[cannot apply to linus/master v6.18-rc4]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Andy-Shevchenko/kernel-doc-Issue-warnings-that-were-silently-discarded/20251105-055629
base:   git://git.lwn.net/linux.git docs-next
patch link:    https://lore.kernel.org/r/20251104215502.1049817-1-andriy.shevchenko%40linux.intel.com
patch subject: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded
config: sh-allnoconfig (https://download.01.org/0day-ci/archive/20251105/202511050706.NIxJwZER-lkp@intel.com/config)
compiler: sh4-linux-gcc (GCC) 15.1.0
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20251105/202511050706.NIxJwZER-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202511050706.NIxJwZER-lkp@intel.com/

All warnings (new ones prefixed by >>):

>> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'd' not described in 'intc_evt_xlate'
>> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'ctrlr' not described in 'intc_evt_xlate'
>> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'intspec' not described in 'intc_evt_xlate'
>> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'intsize' not described in 'intc_evt_xlate'
>> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'out_hwirq' not described in 'intc_evt_xlate'
>> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'out_type' not described in 'intc_evt_xlate'
>> Warning: drivers/sh/intc/irqdomain.c:29 expecting prototype for intc_irq_domain_evt_xlate(). Prototype was for intc_evt_xlate() instead

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Randy Dunlap]

On 11/4/25 1:55 PM, Andy Shevchenko wrote:
> When kernel-doc parses the sections for the documentation some errors
> may occur. In many cases the warning is simply stored to the current
> "entry" object. However, in the most of such cases this object gets
> discarded and there is no way for the output engine to even know about
> that. To avoid that, check if the "entry" is going to be discarded and
> if there warnings have been collected, issue them to the current logger
> as is and then flush the "entry". This fixes the problem that original
> Perl implementation doesn't have.
> 
> As of Linux kernel v6.18-rc4 the reproducer can be:
> 
> $ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h
> ...
> Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr
> ...
> 
> while with the proposed change applied it gives one more line:
> 
> $ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h
> ...
> Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr
> Warning: include/linux/util_macros.h:144 expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead
> ...
> 
> And with the original Perl script:
> 
> $ scripts/kernel-doc.pl -v -none -Wall include/linux/util_macros.h
> ...
> include/linux/util_macros.h:139: info: Scanning doc for function to_user_ptr
> include/linux/util_macros.h:149: warning: expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead
> ...
> 
> Fixes: 9cbc2d3b137b ("scripts/kernel-doc.py: postpone warnings to the output plugin")
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

Oh, thank you. I knew that I had been missing some warnings since
I still compare outputs from the 2 kernel-docs (perl vs. python).

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

> ---
>  scripts/lib/kdoc/kdoc_parser.py | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index ee1a4ea6e725..f7dbb0868367 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -451,6 +451,13 @@ class KernelDoc:
>          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.entry = KernelEntry(self.config, self.fname, ln)
>  
>          # State flags

-- 
~Randy

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Andy Shevchenko]

On Wed, Nov 05, 2025 at 07:14:57AM +0800, kernel test robot wrote:
> Hi Andy,
> 
> kernel test robot noticed the following build warnings:

Right, the change restores the check, so these should be fixed separately.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Andy Shevchenko]

On Wed, Nov 05, 2025 at 07:14:58AM +0800, kernel test robot wrote:
> Hi Andy,
> 
> kernel test robot noticed the following build warnings:

So do these...

> [auto build test WARNING on lwn/docs-next]
> [also build test WARNING on next-20251104]
> [cannot apply to linus/master v6.18-rc4]
> [If your patch is applied to the wrong git tree, kindly drop us a note.
> And when submitting patch, we suggest to use '--base' as documented in
> https://git-scm.com/docs/git-format-patch#_base_tree_information]
> 
> url:    https://github.com/intel-lab-lkp/linux/commits/Andy-Shevchenko/kernel-doc-Issue-warnings-that-were-silently-discarded/20251105-055629
> base:   git://git.lwn.net/linux.git docs-next
> patch link:    https://lore.kernel.org/r/20251104215502.1049817-1-andriy.shevchenko%40linux.intel.com
> patch subject: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded
> config: sh-allnoconfig (https://download.01.org/0day-ci/archive/20251105/202511050706.NIxJwZER-lkp@intel.com/config)
> compiler: sh4-linux-gcc (GCC) 15.1.0
> reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20251105/202511050706.NIxJwZER-lkp@intel.com/reproduce)
> 
> If you fix the issue in a separate patch/commit (i.e. not just a new version of
> the same patch/commit), kindly add following tags
> | Reported-by: kernel test robot <lkp@intel.com>
> | Closes: https://lore.kernel.org/oe-kbuild-all/202511050706.NIxJwZER-lkp@intel.com/
> 
> All warnings (new ones prefixed by >>):
> 
> >> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'd' not described in 'intc_evt_xlate'
> >> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'ctrlr' not described in 'intc_evt_xlate'
> >> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'intspec' not described in 'intc_evt_xlate'
> >> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'intsize' not described in 'intc_evt_xlate'
> >> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'out_hwirq' not described in 'intc_evt_xlate'
> >> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'out_type' not described in 'intc_evt_xlate'
> >> Warning: drivers/sh/intc/irqdomain.c:29 expecting prototype for intc_irq_domain_evt_xlate(). Prototype was for intc_evt_xlate() instead

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Andy Shevchenko]

On Tue, Nov 04, 2025 at 03:18:18PM -0800, Randy Dunlap wrote:
> On 11/4/25 1:55 PM, Andy Shevchenko wrote:
> > When kernel-doc parses the sections for the documentation some errors
> > may occur. In many cases the warning is simply stored to the current
> > "entry" object. However, in the most of such cases this object gets
> > discarded and there is no way for the output engine to even know about
> > that. To avoid that, check if the "entry" is going to be discarded and
> > if there warnings have been collected, issue them to the current logger
> > as is and then flush the "entry". This fixes the problem that original
> > Perl implementation doesn't have.
> > 
> > As of Linux kernel v6.18-rc4 the reproducer can be:
> > 
> > $ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h
> > ...
> > Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr
> > ...
> > 
> > while with the proposed change applied it gives one more line:
> > 
> > $ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h
> > ...
> > Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr
> > Warning: include/linux/util_macros.h:144 expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead
> > ...
> > 
> > And with the original Perl script:
> > 
> > $ scripts/kernel-doc.pl -v -none -Wall include/linux/util_macros.h
> > ...
> > include/linux/util_macros.h:139: info: Scanning doc for function to_user_ptr
> > include/linux/util_macros.h:149: warning: expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead
> > ...
> > 
> > Fixes: 9cbc2d3b137b ("scripts/kernel-doc.py: postpone warnings to the output plugin")
> > Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> 
> Oh, thank you. I knew that I had been missing some warnings

You're welcome! I Cc'ed to you a couple of 0day reports for the missed
warnings.

> since I still compare outputs from the 2 kernel-docs (perl vs. python).

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

Thank you! Jon, can we apply this rather sooner to prevent more missing
warnings, please? If the solution is not good enough, we may amend it
later.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Philip Li]

On Wed, Nov 05, 2025 at 07:27:14AM +0200, Andy Shevchenko wrote:
> On Wed, Nov 05, 2025 at 07:14:58AM +0800, kernel test robot wrote:
> > Hi Andy,
> > 
> > kernel test robot noticed the following build warnings:
> 
> So do these...

Got it, thanks for the info, I will update the bot to ignore the further
reports on this commit. Sorry for the false positive.

Thanks

> 
> > [auto build test WARNING on lwn/docs-next]
> > [also build test WARNING on next-20251104]
> > [cannot apply to linus/master v6.18-rc4]
> > [If your patch is applied to the wrong git tree, kindly drop us a note.
> > And when submitting patch, we suggest to use '--base' as documented in
> > https://git-scm.com/docs/git-format-patch#_base_tree_information]
> > 
> > url:    https://github.com/intel-lab-lkp/linux/commits/Andy-Shevchenko/kernel-doc-Issue-warnings-that-were-silently-discarded/20251105-055629
> > base:   git://git.lwn.net/linux.git docs-next
> > patch link:    https://lore.kernel.org/r/20251104215502.1049817-1-andriy.shevchenko%40linux.intel.com
> > patch subject: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded
> > config: sh-allnoconfig (https://download.01.org/0day-ci/archive/20251105/202511050706.NIxJwZER-lkp@intel.com/config)
> > compiler: sh4-linux-gcc (GCC) 15.1.0
> > reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20251105/202511050706.NIxJwZER-lkp@intel.com/reproduce)
> > 
> > If you fix the issue in a separate patch/commit (i.e. not just a new version of
> > the same patch/commit), kindly add following tags
> > | Reported-by: kernel test robot <lkp@intel.com>
> > | Closes: https://lore.kernel.org/oe-kbuild-all/202511050706.NIxJwZER-lkp@intel.com/
> > 
> > All warnings (new ones prefixed by >>):
> > 
> > >> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'd' not described in 'intc_evt_xlate'
> > >> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'ctrlr' not described in 'intc_evt_xlate'
> > >> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'intspec' not described in 'intc_evt_xlate'
> > >> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'intsize' not described in 'intc_evt_xlate'
> > >> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'out_hwirq' not described in 'intc_evt_xlate'
> > >> Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'out_type' not described in 'intc_evt_xlate'
> > >> Warning: drivers/sh/intc/irqdomain.c:29 expecting prototype for intc_irq_domain_evt_xlate(). Prototype was for intc_evt_xlate() instead
> 
> -- 
> With Best Regards,
> Andy Shevchenko
> 
> 
> 

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Andy Shevchenko]

On Wed, Nov 05, 2025 at 03:48:20PM +0800, Philip Li wrote:
> On Wed, Nov 05, 2025 at 07:27:14AM +0200, Andy Shevchenko wrote:
> > On Wed, Nov 05, 2025 at 07:14:58AM +0800, kernel test robot wrote:
> > > 
> > > kernel test robot noticed the following build warnings:
> > 
> > So do these...
> 
> Got it, thanks for the info, I will update the bot to ignore the further
> reports on this commit. Sorry for the false positive.

No, they are not false positives, they are legit and good to have. Just that
the root cause is not this commit.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Philip Li]

On Wed, Nov 05, 2025 at 12:02:58PM +0200, Andy Shevchenko wrote:
> On Wed, Nov 05, 2025 at 03:48:20PM +0800, Philip Li wrote:
> > On Wed, Nov 05, 2025 at 07:27:14AM +0200, Andy Shevchenko wrote:
> > > On Wed, Nov 05, 2025 at 07:14:58AM +0800, kernel test robot wrote:
> > > > 
> > > > kernel test robot noticed the following build warnings:
> > > 
> > > So do these...
> > 
> > Got it, thanks for the info, I will update the bot to ignore the further
> > reports on this commit. Sorry for the false positive.
> 
> No, they are not false positives, they are legit and good to have. Just that
> the root cause is not this commit.

Thanks Andy, got it. I will add comments clearly to be part of bot configuration.

> 
> -- 
> With Best Regards,
> Andy Shevchenko
> 
> 

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Jonathan Corbet]

[Heads up to Stephen: this change will add a bunch of warnings that had
been dropped before.]

Andy Shevchenko <andriy.shevchenko@linux.intel.com> writes:

> When kernel-doc parses the sections for the documentation some errors
> may occur. In many cases the warning is simply stored to the current
> "entry" object. However, in the most of such cases this object gets
> discarded and there is no way for the output engine to even know about
> that. To avoid that, check if the "entry" is going to be discarded and
> if there warnings have been collected, issue them to the current logger
> as is and then flush the "entry". This fixes the problem that original
> Perl implementation doesn't have.

I would really like to redo how some of that logging is done, but that
is an exercise for another day.  For now, I have applied this one,
thanks.

jon

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Andy Shevchenko]

On Wed, Nov 05, 2025 at 11:12:18AM -0700, Jonathan Corbet wrote:
> [Heads up to Stephen: this change will add a bunch of warnings that had
> been dropped before.]
> 
> Andy Shevchenko <andriy.shevchenko@linux.intel.com> writes:
> 
> > When kernel-doc parses the sections for the documentation some errors
> > may occur. In many cases the warning is simply stored to the current
> > "entry" object. However, in the most of such cases this object gets
> > discarded and there is no way for the output engine to even know about
> > that. To avoid that, check if the "entry" is going to be discarded and
> > if there warnings have been collected, issue them to the current logger
> > as is and then flush the "entry". This fixes the problem that original
> > Perl implementation doesn't have.
> 
> I would really like to redo how some of that logging is done, but that
> is an exercise for another day.  For now, I have applied this one,
> thanks.

Thank you!

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Mauro Carvalho Chehab]

Em Tue,  4 Nov 2025 22:55:02 +0100
Andy Shevchenko <andriy.shevchenko@linux.intel.com> escreveu:

> When kernel-doc parses the sections for the documentation some errors
> may occur. In many cases the warning is simply stored to the current
> "entry" object. However, in the most of such cases this object gets
> discarded and there is no way for the output engine to even know about
> that. To avoid that, check if the "entry" is going to be discarded and
> if there warnings have been collected, issue them to the current logger
> as is and then flush the "entry". This fixes the problem that original
> Perl implementation doesn't have.
> 
> As of Linux kernel v6.18-rc4 the reproducer can be:
> 
> $ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h
> ...
> Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr
> ...
> 
> while with the proposed change applied it gives one more line:
> 
> $ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h
> ...
> Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr
> Warning: include/linux/util_macros.h:144 expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead
> ...
> 
> And with the original Perl script:
> 
> $ scripts/kernel-doc.pl -v -none -Wall include/linux/util_macros.h
> ...
> include/linux/util_macros.h:139: info: Scanning doc for function to_user_ptr
> include/linux/util_macros.h:149: warning: expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead
> ...
> 
> Fixes: 9cbc2d3b137b ("scripts/kernel-doc.py: postpone warnings to the output plugin")
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> ---
>  scripts/lib/kdoc/kdoc_parser.py | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index ee1a4ea6e725..f7dbb0868367 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -451,6 +451,13 @@ class KernelDoc:
>          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.entry = KernelEntry(self.config, self.fname, ln)
>  
>          # State flags

No objection of this one, but this breaks the behavior of the -W
flags.

See, the way kernel-doc.pl worked is that:

1. Warnings are controlled via several -W flags:

  -Wreturn, --wreturn   Warns about the lack of a return markup on functions.
  -Wshort-desc, -Wshort-description, --wshort-desc
                        Warns if initial short description is missing

                        This option is kept just for backward-compatibility, but it does nothing,
                        neither here nor at the original Perl script.
  -Wall, --wall         Enable all types of warnings
  -Werror, --werror     Treat warnings as errors.

  Those affect running kernel-doc manually.

2. Warnings are affected by the filtering commands:

  -e, -export, --export
                        
                        Only output documentation for the symbols that have been
                        exported using EXPORT_SYMBOL() and related macros in any input
                        FILE or -export-file FILE.
  -i, -internal, --internal
                        
                        Only output documentation for the symbols that have NOT been
                        exported using EXPORT_SYMBOL() and related macros in any input
                        FILE or -export-file FILE.
  -s, -function, --symbol SYMBOL
                        
                        Only output documentation for the given function or DOC: section
                        title. All other functions and DOC: sections are ignored.
                        
                        May be used multiple times.


  Those affect both running kernel-doc manually or when called via make htmldocs,
  as the kerneldoc Sphinx markup supports them.

As the filters are only applied at kdoc/kdoc_output.py, printing warnings
early at kdoc_parser means that, even ignored symbols will be warned. It might
also make the same warning to appear more than once, for C files that are listed
on multiple kerneldoc entries(*).

(*) There is a logic at kerneldoc.py Sphinx extension and inside kdoc_files
    to avoid parsing the same file twice, but I didn't test adding a hack
    similar to this one to double-check that the warning won't appear multiple
    times when export is used. Maybe it is working fine.

-

In summary, if warnings are suppressed, my suggestion would be to check at 
kdoc_output to see what is filtering them out. 

Alternatively, if the idea is to always print warnings, get rid of all
-W<option> flags, except for -Werror.

Thanks,
Mauro

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Randy Dunlap]

On 11/5/25 1:19 PM, Mauro Carvalho Chehab wrote:
> 
> No objection of this one, but this breaks the behavior of the -W
> flags.
> 
> See, the way kernel-doc.pl worked is that:
> 
> 1. Warnings are controlled via several -W flags:
> 
>   -Wreturn, --wreturn   Warns about the lack of a return markup on functions.
>   -Wshort-desc, -Wshort-description, --wshort-desc
>                         Warns if initial short description is missing
> 
>                         This option is kept just for backward-compatibility, but it does nothing,
>                         neither here nor at the original Perl script.

FWIW, it did output warnings once upon a time (the Perl script version).
I don't know what happened to it.

>   -Wall, --wall         Enable all types of warnings
>   -Werror, --werror     Treat warnings as errors.
> 
>   Those affect running kernel-doc manually.
-- 
~Randy

Re: [BUILD REGRESSION] LAST PATCH: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Andy Shevchenko]

On Thu, Nov 06, 2025 at 06:22:07AM +0800, kernel test robot wrote:
> url:    https://github.com/intel-lab-lkp/linux/commits/Andy-Shevchenko/kernel-doc-Issue-warnings-that-were-silently-discarded/20251105-055629
> base:   git://git.lwn.net/linux.git docs-next
> patch link:    https://lore.kernel.org/r/20251104215502.1049817-1-andriy.shevchenko%40linux.intel.com
> patch subject: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded
> 
> [If your patch is applied to the wrong git tree, kindly drop us a note.
> And when submitting patch, we suggest to use '--base' as documented in
> https://git-scm.com/docs/git-format-patch#_base_tree_information]
> 
> Error/Warning (recently discovered and may have been fixed):

Yeah, this is what we missed for these half a year...

>     https://lore.kernel.org/oe-kbuild-all/202511050706.NIxJwZER-lkp@intel.com
>     https://lore.kernel.org/oe-kbuild-all/202511050720.nJ9ccENC-lkp@intel.com
> 
>     Warning: arch/powerpc/kernel/eeh_driver.c:761 expecting prototype for eeh_check_slot_presence(). Prototype was for eeh_slot_presence_check() instead
>     Warning: arch/powerpc/kernel/eeh_event.c:102 expecting prototype for eeh_send_failure_event(). Prototype was for __eeh_send_failure_event() instead
>     Warning: arch/powerpc/kernel/eeh_pe.c:567 expecting prototype for eeh_pe_dev_state_mark(). Prototype was for eeh_pe_dev_mode_mark() instead
>     Warning: arch/powerpc/kernel/eeh_pe.c:567 function parameter 'mode' not described in 'eeh_pe_dev_mode_mark'
>     Warning: arch/powerpc/kernel/isa-bridge.c:157 expecting prototype for isa_bridge_find_early(). Prototype was for isa_bridge_init_non_pci() instead
>     Warning: arch/powerpc/kernel/isa-bridge.c:157 function parameter 'np' not described in 'isa_bridge_init_non_pci'
>     Warning: arch/powerpc/kernel/pci-common.c:1645 expecting prototype for pci_scan_phb(). Prototype was for pcibios_scan_phb() instead
>     Warning: arch/powerpc/kernel/pci_of_scan.c:60 expecting prototype for pci_parse_of_flags(). Prototype was for OF_PCI_ADDR0_SPACE() instead
>     Warning: arch/powerpc/kernel/pci_of_scan.c:60 function parameter 'ss' not described in 'OF_PCI_ADDR0_SPACE'
>     Warning: arch/powerpc/kernel/setup-common.c:453 expecting prototype for setup_cpu_maps(). Prototype was for smp_setup_cpu_maps() instead
>     Warning: arch/powerpc/platforms/52xx/mpc52xx_gpt.c:98 expecting prototype for struct mpc52xx_gpt. Prototype was for struct mpc52xx_gpt_priv instead
>     Warning: arch/powerpc/platforms/cell/spu_base.c:222 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>     Warning: arch/powerpc/platforms/cell/spufs/sched.c:475 expecting prototype for spu_add_to_rq(). Prototype was for __spu_add_to_rq() instead
>     Warning: arch/powerpc/platforms/cell/spufs/switch.c:2182 expecting prototype for spu_alloc_csa(). Prototype was for spu_init_csa() instead
>     Warning: arch/powerpc/platforms/cell/spufs/switch.c:2182 function parameter 'csa' not described in 'spu_init_csa'
>     Warning: arch/powerpc/platforms/cell/spufs/syscalls.c:36 expecting prototype for sys_spu_run(). Prototype was for do_spu_run() instead
>     Warning: arch/powerpc/platforms/cell/spufs/syscalls.c:36 function parameter 'filp' not described in 'do_spu_run'
>     Warning: arch/powerpc/platforms/powernv/eeh-powernv.c:1166 expecting prototype for pnv_pe_err_inject(). Prototype was for pnv_eeh_err_inject() instead
>     Warning: arch/powerpc/platforms/ps3/htab.c:28 expecting prototype for enum lpar_vas_id. Prototype was for enum ps3_lpar_vas_id instead
>     Warning: arch/powerpc/platforms/ps3/interrupt.c:150 cannot understand function prototype: 'struct irq_chip ps3_irq_chip ='
>     Warning: arch/powerpc/platforms/ps3/interrupt.c:55 #define PS3_BMP_MINALIGN 64; error: Cannot parse struct or union!
>     Warning: arch/powerpc/platforms/ps3/mm.c:1092 expecting prototype for dma_unmap_area_linear(). Prototype was for dma_sb_unmap_area_linear() instead
>     Warning: arch/powerpc/platforms/ps3/mm.c:708 expecting prototype for dma_region_free(). Prototype was for dma_sb_region_free() instead
>     Warning: arch/powerpc/platforms/ps3/smp.c:26 expecting prototype for ps3_ipi_virqs(). Prototype was for MSG_COUNT() instead
>     Warning: arch/powerpc/platforms/pseries/lpar.c:1080 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>     Warning: arch/powerpc/platforms/pseries/setup.c:945 expecting prototype for fw_cmo_feature_init(). Prototype was for pSeries_cmo_feature_init() instead
>     Warning: arch/powerpc/platforms/pseries/vio.c:106 expecting prototype for vio_cmo_OF_devices(). Prototype was for vio_cmo_num_OF_devs() instead
>     Warning: arch/powerpc/platforms/pseries/vio.c:1286 expecting prototype for vio_register_driver(). Prototype was for __vio_register_driver() instead
>     Warning: arch/powerpc/platforms/pseries/vio.c:1286 function parameter 'mod_name' not described in '__vio_register_driver'
>     Warning: arch/powerpc/platforms/pseries/vio.c:1286 function parameter 'owner' not described in '__vio_register_driver'
>     Warning: arch/powerpc/platforms/pseries/vio.c:51 cannot understand function prototype: 'struct vio_cmo_pool'
>     Warning: arch/powerpc/platforms/pseries/vio.c:68 cannot understand function prototype: 'struct vio_cmo_dev_entry'
>     Warning: arch/powerpc/platforms/pseries/vio.c:88 cannot understand function prototype: 'struct vio_cmo'
>     Warning: arch/x86/kernel/apic/apic.c:2145 expecting prototype for spurious_interrupt(). Prototype was for DEFINE_IDTENTRY_IRQ() instead
>     Warning: arch/x86/kernel/apic/apic.c:2145 function parameter 'spurious_interrupt' not described in 'DEFINE_IDTENTRY_IRQ'
>     Warning: block/blk-mq-dma.c:374 expecting prototype for blk_rq_integrity_dma_map_iter_start(). Prototype was for blk_rq_integrity_dma_map_iter_next() instead
>     Warning: drivers/dma/bestcomm/gen_bd.c:261 cannot understand function prototype: 'struct bcom_psc_params'
>     Warning: drivers/dpll/zl3073x/fw.c:365 expecting prototype for zl3073x_flash_bundle_flash(). Prototype was for zl3073x_fw_component_flash() instead
>     Warning: drivers/dpll/zl3073x/fw.c:365 function parameter 'comp' not described in 'zl3073x_fw_component_flash'
>     Warning: drivers/gpu/drm/msm/msm_gem_vma.c:96 expecting prototype for struct msm_vma_op. Prototype was for struct msm_vm_op instead
>     Warning: drivers/gpu/drm/msm/msm_iommu.c:376 expecting prototype for alloc_pt(). Prototype was for msm_iommu_pagetable_alloc_pt() instead
>     Warning: drivers/gpu/drm/msm/msm_iommu.c:421 expecting prototype for free_pt(). Prototype was for msm_iommu_pagetable_free_pt() instead
>     Warning: drivers/gpu/drm/xe/xe_migrate.c:1128 expecting prototype for xe_get_migrate_exec_queue(). Prototype was for xe_migrate_exec_queue() instead
>     Warning: drivers/gpu/drm/xe/xe_sriov_vf.c:303 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>     Warning: drivers/gpu/drm/xe/xe_tlb_inval.c:126 expecting prototype for xe_gt_tlb_inval_init(). Prototype was for xe_gt_tlb_inval_init_early() instead
>     Warning: drivers/gpu/drm/xe/xe_tlb_inval_job.c:164 expecting prototype for xe_tlb_inval_alloc_dep(). Prototype was for xe_tlb_inval_job_alloc_dep() instead
>     Warning: drivers/md/bcache/request.c:308 expecting prototype for bch_data_insert(). Prototype was for CLOSURE_CALLBACK() instead
>     Warning: drivers/md/bcache/request.c:308 function parameter 'bch_data_insert' not described in 'CLOSURE_CALLBACK'
>     Warning: drivers/net/pse-pd/pse_core.c:246 expecting prototype for pse_control_find_net_by_id(). Prototype was for pse_control_find_by_id() instead
>     Warning: drivers/ps3/ps3-lpm.c:1056 expecting prototype for ps3_enable_pm_interrupts(). Prototype was for ps3_disable_pm_interrupts() instead
>     Warning: drivers/ps3/ps3-lpm.c:1056 function parameter 'cpu' not described in 'ps3_disable_pm_interrupts'
>     Warning: drivers/ps3/ps3-lpm.c:143 cannot understand function prototype: 'struct ps3_lpm_priv *lpm_priv;'
>     Warning: drivers/ps3/ps3-lpm.c:161 cannot understand function prototype: 'enum'
>     Warning: drivers/ps3/ps3-sys-manager.c:198 cannot understand function prototype: 'u32 user_wake_sources = PS3_SM_WAKE_DEFAULT;'
>     Warning: drivers/ps3/ps3-sys-manager.c:222 cannot understand function prototype: 'unsigned int ps3_sm_force_power_off;'
>     Warning: drivers/ps3/ps3-sys-manager.c:35 Incorrect use of kernel-doc format:  * struct ps3_sys_manager_header - System manager message header.
>     Warning: drivers/ps3/ps3-sys-manager.c:43 cannot understand function prototype: '* @version: Header version, currently 1.  * @size: Header size in bytes, currently 16.  * @payload_size: Message payload size in bytes.  * @service_id: Message type, one of enum ps3_sys_manager_service_id.  * @request_tag: Unique number to identify reply.  */  struct ps3_sys_manager_header'
>     Warning: drivers/ps3/ps3-sys-manager.c:66 Cannot find identifier on line:
>     Warning: drivers/ps3/ps3-sys-manager.c:69 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>     Warning: drivers/ps3/ps3-vuart.c:36 cannot understand function prototype: 'enum'
>     Warning: drivers/ps3/sys-manager-core.c:14 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>     Warning: drivers/ps3/sys-manager-core.c:30 expecting prototype for ps3_register_sys_manager_ops(). Prototype was for ps3_sys_manager_register_ops() instead
>     Warning: drivers/regulator/pf9453-regulator.c:303 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>     Warning: drivers/scsi/mpt3sas/mpt3sas_ctl.c:2913 expecting prototype for mpt3sas_send_passthru_cmd(). Prototype was for mpt3sas_send_mctp_passthru_req() instead
>     Warning: drivers/sh/intc/irqdomain.c:29 expecting prototype for intc_irq_domain_evt_xlate(). Prototype was for intc_evt_xlate() instead
>     Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'ctrlr' not described in 'intc_evt_xlate'
>     Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'd' not described in 'intc_evt_xlate'
>     Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'intsize' not described in 'intc_evt_xlate'
>     Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'intspec' not described in 'intc_evt_xlate'
>     Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'out_hwirq' not described in 'intc_evt_xlate'
>     Warning: drivers/sh/intc/irqdomain.c:29 function parameter 'out_type' not described in 'intc_evt_xlate'
>     Warning: drivers/tty/serial/mux.c:351 expecting prototype for mux_drv_poll(). Prototype was for mux_poll() instead
>     Warning: drivers/video/fbdev/mmp/hw/mmp_spi.c:30 expecting prototype for spi_write(). Prototype was for lcd_spi_write() instead
>     Warning: drivers/virtio/virtio_ring.c:3308 expecting prototype for virtqueue_mapping_error(). Prototype was for virtqueue_map_mapping_error() instead
>     Warning: fs/befs/datastream.c:131 expecting prototype for befs_read_lsmylink(). Prototype was for befs_read_lsymlink() instead
>     Warning: ipc/sem.c:629 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>     Warning: kernel/nstree.c:215 expecting prototype for ns_tree_adjoined_rcu(). Prototype was for __ns_tree_adjoined_rcu() instead
>     Warning: kernel/nstree.c:215 function parameter 'ns_tree' not described in '__ns_tree_adjoined_rcu'
>     Warning: lib/hweight.c:13 expecting prototype for hweightN(). Prototype was for __sw_hweight32() instead
>     Warning: lib/hweight.c:13 function parameter 'w' not described in '__sw_hweight32'
>     Warning: mm/swap_state.c:294 expecting prototype for swap_cache_clear_shadow(). Prototype was for __swap_cache_clear_shadow() instead
>     Warning: mm/vmalloc.c:4129 expecting prototype for vrealloc_node_align_noprof(). Prototype was for vrealloc_node_align() instead
>     Warning: security/apparmor/af_unix.c:618 Cannot find identifier on line:
>     Warning: security/apparmor/af_unix.c:626 expecting prototype for Requires(). Prototype was for aa_unix_peer_perm() instead
>     Warning: security/apparmor/af_unix.c:626 function parameter 'label' not described in 'aa_unix_peer_perm'
>     Warning: security/apparmor/af_unix.c:626 function parameter 'op' not described in 'aa_unix_peer_perm'
>     Warning: security/apparmor/af_unix.c:626 function parameter 'peer_label' not described in 'aa_unix_peer_perm'
>     Warning: security/apparmor/af_unix.c:626 function parameter 'peer_sk' not described in 'aa_unix_peer_perm'
>     Warning: security/apparmor/af_unix.c:626 function parameter 'request' not described in 'aa_unix_peer_perm'
>     Warning: security/apparmor/af_unix.c:626 function parameter 'sk' not described in 'aa_unix_peer_perm'
>     Warning: security/apparmor/af_unix.c:626 function parameter 'subj_cred' not described in 'aa_unix_peer_perm'
>     Warning: sound/soc/fsl/mpc5200_psc_ac97.c:222 cannot understand function prototype: 'const struct snd_soc_dai_ops psc_ac97_analog_ops ='
>     Warning: sound/soc/fsl/mpc5200_psc_i2s.c:123 cannot understand function prototype: 'const struct snd_soc_dai_ops psc_i2s_dai_ops ='
>     Warning: sound/usb/usx2y/us144mkii.c:13 Cannot find identifier on line:
>     Warning: sound/usb/usx2y/us144mkii.c:15 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>     Warning: sound/usb/usx2y/us144mkii_capture.c:100 cannot understand function prototype: 'const struct snd_pcm_ops tascam_capture_ops ='
>     Warning: sound/usb/usx2y/us144mkii_controls.c:100 cannot understand function prototype: 'const struct snd_kcontrol_new tascam_line_out_control ='
>     Warning: sound/usb/usx2y/us144mkii_controls.c:171 cannot understand function prototype: 'const struct snd_kcontrol_new tascam_digital_out_control ='
>     Warning: sound/usb/usx2y/us144mkii_controls.c:259 cannot understand function prototype: 'const struct snd_kcontrol_new tascam_capture_12_control ='
>     Warning: sound/usb/usx2y/us144mkii_controls.c:330 cannot understand function prototype: 'const struct snd_kcontrol_new tascam_capture_34_control ='
>     Warning: sound/usb/usx2y/us144mkii_controls.c:408 cannot understand function prototype: 'const struct snd_kcontrol_new tascam_samplerate_control ='
>     Warning: sound/usb/usx2y/us144mkii_controls.c:6 Cannot find identifier on line:
>     Warning: sound/usb/usx2y/us144mkii_controls.c:8 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>     Warning: sound/usb/usx2y/us144mkii_midi.c:158 cannot understand function prototype: 'const struct snd_rawmidi_ops tascam_midi_in_ops ='
>     Warning: sound/usb/usx2y/us144mkii_midi.c:369 cannot understand function prototype: 'const struct snd_rawmidi_ops tascam_midi_out_ops ='
>     Warning: sound/usb/usx2y/us144mkii_playback.c:146 cannot understand function prototype: 'const struct snd_pcm_ops tascam_playback_ops ='
> 
> Unverified Error/Warning (likely false positive, kindly check if interested):
> 
>     Warning: arch/arm/mach-omap2/cpuidle44xx.c:75 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>     Warning: arch/arm/mach-omap2/prm33xx.c:322 expecting prototype for am33xx_prm_global_warm_sw_reset(). Prototype was for am33xx_prm_global_sw_reset() instead
>     Warning: drivers/char/xilinx_hwicap/fifo_icap.c:357 expecting prototype for buffer_icap_reset(). Prototype was for fifo_icap_reset() instead
>     Warning: drivers/char/xilinx_hwicap/fifo_icap.c:51 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>     Warning: drivers/clk/zynq/pll.c:52 expecting prototype for zynq_pll_round_rate(). Prototype was for zynq_pll_determine_rate() instead
>     Warning: drivers/clk/zynq/pll.c:52 function parameter 'req' not described in 'zynq_pll_determine_rate'
>     Warning: drivers/clk/zynqmp/divider.c:122 expecting prototype for zynqmp_clk_divider_round_rate(). Prototype was for zynqmp_clk_divider_determine_rate() instead
>     Warning: drivers/clk/zynqmp/divider.c:122 function parameter 'req' not described in 'zynqmp_clk_divider_determine_rate'
>     Warning: drivers/clk/zynqmp/pll.c:102 expecting prototype for zynqmp_pll_round_rate(). Prototype was for zynqmp_pll_determine_rate() instead
>     Warning: drivers/clk/zynqmp/pll.c:102 function parameter 'req' not described in 'zynqmp_pll_determine_rate'
>     Warning: drivers/cpufreq/gx-suspmod.c:142 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>     Warning: drivers/cpufreq/longrun.c:125 expecting prototype for longrun_verify_poliy(). Prototype was for longrun_verify_policy() instead
>     Warning: drivers/cpufreq/longrun.c:20 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>     Warning: drivers/gpu/drm/drm_gpusvm.c:1229 expecting prototype for drm_gpusvm_range_pages_valid_unlocked(). Prototype was for drm_gpusvm_pages_valid_unlocked() instead
>     Warning: drivers/gpu/drm/drm_gpusvm.c:1229 function parameter 'svm_pages' not described in 'drm_gpusvm_pages_valid_unlocked'
>     Warning: drivers/infiniband/hw/mlx5/umr.c:986 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>     Warning: drivers/mailbox/mailbox-xgene-slimpro.c:42 cannot understand function prototype: 'struct slimpro_mbox_chan'
>     Warning: drivers/mailbox/mailbox-xgene-slimpro.c:61 cannot understand function prototype: 'struct slimpro_mbox'
>     Warning: drivers/net/ethernet/intel/idpf/idpf_txrx.c:2407 expecting prototype for idpf_tx_splitq_has_room(). Prototype was for idpf_txq_has_room() instead
>     Warning: sound/soc/sdca/sdca_interrupts.c:265 expecting prototype for sdca_request_irq(). Prototype was for sdca_irq_request() instead
>     Warning: sound/soc/sdca/sdca_interrupts.c:265 function parameter 'info' not described in 'sdca_irq_request'

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Andy Shevchenko]

On Wed, Nov 05, 2025 at 10:19:07PM +0100, Mauro Carvalho Chehab wrote:
> Em Tue,  4 Nov 2025 22:55:02 +0100
> Andy Shevchenko <andriy.shevchenko@linux.intel.com> escreveu:
> 
> > When kernel-doc parses the sections for the documentation some errors
> > may occur. In many cases the warning is simply stored to the current
> > "entry" object. However, in the most of such cases this object gets
> > discarded and there is no way for the output engine to even know about
> > that. To avoid that, check if the "entry" is going to be discarded and
> > if there warnings have been collected, issue them to the current logger
> > as is and then flush the "entry". This fixes the problem that original
> > Perl implementation doesn't have.
> > 
> > As of Linux kernel v6.18-rc4 the reproducer can be:
> > 
> > $ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h
> > ...
> > Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr
> > ...
> > 
> > while with the proposed change applied it gives one more line:
> > 
> > $ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h
> > ...
> > Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr
> > Warning: include/linux/util_macros.h:144 expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead
> > ...
> > 
> > And with the original Perl script:
> > 
> > $ scripts/kernel-doc.pl -v -none -Wall include/linux/util_macros.h
> > ...
> > include/linux/util_macros.h:139: info: Scanning doc for function to_user_ptr
> > include/linux/util_macros.h:149: warning: expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead
> > ...
> > 
> > Fixes: 9cbc2d3b137b ("scripts/kernel-doc.py: postpone warnings to the output plugin")
> > Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> > ---
> >  scripts/lib/kdoc/kdoc_parser.py | 7 +++++++
> >  1 file changed, 7 insertions(+)
> > 
> > diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> > index ee1a4ea6e725..f7dbb0868367 100644
> > --- a/scripts/lib/kdoc/kdoc_parser.py
> > +++ b/scripts/lib/kdoc/kdoc_parser.py
> > @@ -451,6 +451,13 @@ class KernelDoc:
> >          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.entry = KernelEntry(self.config, self.fname, ln)
> >  
> >          # State flags
> 
> No objection of this one, but this breaks the behavior of the -W
> flags.

Sorry for that, but at least now the outcome is much better than before.

> See, the way kernel-doc.pl worked is that:
> 
> 1. Warnings are controlled via several -W flags:
> 
>   -Wreturn, --wreturn   Warns about the lack of a return markup on functions.
>   -Wshort-desc, -Wshort-description, --wshort-desc
>                         Warns if initial short description is missing
> 
>                         This option is kept just for backward-compatibility, but it does nothing,
>                         neither here nor at the original Perl script.
>   -Wall, --wall         Enable all types of warnings
>   -Werror, --werror     Treat warnings as errors.
> 
>   Those affect running kernel-doc manually.
> 
> 2. Warnings are affected by the filtering commands:
> 
>   -e, -export, --export
>                         
>                         Only output documentation for the symbols that have been
>                         exported using EXPORT_SYMBOL() and related macros in any input
>                         FILE or -export-file FILE.
>   -i, -internal, --internal
>                         
>                         Only output documentation for the symbols that have NOT been
>                         exported using EXPORT_SYMBOL() and related macros in any input
>                         FILE or -export-file FILE.
>   -s, -function, --symbol SYMBOL
>                         
>                         Only output documentation for the given function or DOC: section
>                         title. All other functions and DOC: sections are ignored.
>                         
>                         May be used multiple times.
> 
> 
>   Those affect both running kernel-doc manually or when called via make htmldocs,
>   as the kerneldoc Sphinx markup supports them.
> 
> As the filters are only applied at kdoc/kdoc_output.py, printing warnings
> early at kdoc_parser means that, even ignored symbols will be warned.

Maybe I failed to make the point of the reproducer. The kernel doc and prototype
are mismatched, and hence there is no way one may filter this in accordance
with the logic I read. These warnings must be printed independently on the
filters as filters may not be applied to this. Or i.o.w. what has one to put to
-s for the reproducer case to make it visible? Also what should one put to make
it on par with the previous behaviour?

> It might
> also make the same warning to appear more than once, for C files that are listed
> on multiple kerneldoc entries(*).
> 
> (*) There is a logic at kerneldoc.py Sphinx extension and inside kdoc_files
>     to avoid parsing the same file twice, but I didn't test adding a hack
>     similar to this one to double-check that the warning won't appear multiple
>     times when export is used. Maybe it is working fine.
> 
> -
> 
> In summary, if warnings are suppressed, my suggestion would be to check at 
> kdoc_output to see what is filtering them out. 

In the commit message I tried to explain the situation. These warning are
vanished _before any_ output plugin is run. There is *no way* to get them
printed otherwise.  It's, of course, possible that I haven't got deeply the
idea behind architecture of the logging in the Python script. I am all ears for
the improvements that satisfy everybody.

I think the problem is in design, it needs to be redone as Jon said.

> Alternatively, if the idea is to always print warnings, get rid of all
> -W<option> flags, except for -Werror.

Not sure it's wanted behaviour, but I am in favour for anything that makes
warning visible and not silently disappear.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Andy Shevchenko]

On Thu, Nov 06, 2025 at 09:31:41AM +0200, Andy Shevchenko wrote:
> On Wed, Nov 05, 2025 at 10:19:07PM +0100, Mauro Carvalho Chehab wrote:
> > Em Tue,  4 Nov 2025 22:55:02 +0100
> > Andy Shevchenko <andriy.shevchenko@linux.intel.com> escreveu:
> > 
> > > When kernel-doc parses the sections for the documentation some errors
> > > may occur. In many cases the warning is simply stored to the current
> > > "entry" object. However, in the most of such cases this object gets
> > > discarded and there is no way for the output engine to even know about
> > > that. To avoid that, check if the "entry" is going to be discarded and
> > > if there warnings have been collected, issue them to the current logger
> > > as is and then flush the "entry". This fixes the problem that original
> > > Perl implementation doesn't have.
> > > 
> > > As of Linux kernel v6.18-rc4 the reproducer can be:
> > > 
> > > $ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h
> > > ...
> > > Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr
> > > ...
> > > 
> > > while with the proposed change applied it gives one more line:
> > > 
> > > $ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h
> > > ...
> > > Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr
> > > Warning: include/linux/util_macros.h:144 expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead
> > > ...
> > > 
> > > And with the original Perl script:
> > > 
> > > $ scripts/kernel-doc.pl -v -none -Wall include/linux/util_macros.h
> > > ...
> > > include/linux/util_macros.h:139: info: Scanning doc for function to_user_ptr
> > > include/linux/util_macros.h:149: warning: expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead
> > > ...
> > > 
> > > Fixes: 9cbc2d3b137b ("scripts/kernel-doc.py: postpone warnings to the output plugin")
> > > Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> > > ---
> > >  scripts/lib/kdoc/kdoc_parser.py | 7 +++++++
> > >  1 file changed, 7 insertions(+)
> > > 
> > > diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> > > index ee1a4ea6e725..f7dbb0868367 100644
> > > --- a/scripts/lib/kdoc/kdoc_parser.py
> > > +++ b/scripts/lib/kdoc/kdoc_parser.py
> > > @@ -451,6 +451,13 @@ class KernelDoc:
> > >          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.entry = KernelEntry(self.config, self.fname, ln)
> > >  
> > >          # State flags
> > 
> > No objection of this one, but this breaks the behavior of the -W
> > flags.
> 
> Sorry for that, but at least now the outcome is much better than before.
> 
> > See, the way kernel-doc.pl worked is that:
> > 
> > 1. Warnings are controlled via several -W flags:
> > 
> >   -Wreturn, --wreturn   Warns about the lack of a return markup on functions.
> >   -Wshort-desc, -Wshort-description, --wshort-desc
> >                         Warns if initial short description is missing
> > 
> >                         This option is kept just for backward-compatibility, but it does nothing,
> >                         neither here nor at the original Perl script.
> >   -Wall, --wall         Enable all types of warnings
> >   -Werror, --werror     Treat warnings as errors.
> > 
> >   Those affect running kernel-doc manually.
> > 
> > 2. Warnings are affected by the filtering commands:
> > 
> >   -e, -export, --export
> >                         
> >                         Only output documentation for the symbols that have been
> >                         exported using EXPORT_SYMBOL() and related macros in any input
> >                         FILE or -export-file FILE.
> >   -i, -internal, --internal
> >                         
> >                         Only output documentation for the symbols that have NOT been
> >                         exported using EXPORT_SYMBOL() and related macros in any input
> >                         FILE or -export-file FILE.
> >   -s, -function, --symbol SYMBOL
> >                         
> >                         Only output documentation for the given function or DOC: section
> >                         title. All other functions and DOC: sections are ignored.
> >                         
> >                         May be used multiple times.
> > 
> > 
> >   Those affect both running kernel-doc manually or when called via make htmldocs,
> >   as the kerneldoc Sphinx markup supports them.
> > 
> > As the filters are only applied at kdoc/kdoc_output.py, printing warnings
> > early at kdoc_parser means that, even ignored symbols will be warned.
> 
> Maybe I failed to make the point of the reproducer. The kernel doc and prototype
> are mismatched, and hence there is no way one may filter this in accordance
> with the logic I read. These warnings must be printed independently on the
> filters as filters may not be applied to this. Or i.o.w. what has one to put to
> -s for the reproducer case to make it visible? Also what should one put to make
> it on par with the previous behaviour?
> 
> > It might
> > also make the same warning to appear more than once, for C files that are listed
> > on multiple kerneldoc entries(*).
> > 
> > (*) There is a logic at kerneldoc.py Sphinx extension and inside kdoc_files
> >     to avoid parsing the same file twice, but I didn't test adding a hack
> >     similar to this one to double-check that the warning won't appear multiple
> >     times when export is used. Maybe it is working fine.
> > 
> > -
> > 
> > In summary, if warnings are suppressed, my suggestion would be to check at 
> > kdoc_output to see what is filtering them out. 
> 
> In the commit message I tried to explain the situation. These warning are
> vanished _before any_ output plugin is run. There is *no way* to get them
> printed otherwise.  It's, of course, possible that I haven't got deeply the
> idea behind architecture of the logging in the Python script. I am all ears for
> the improvements that satisfy everybody.
> 
> I think the problem is in design, it needs to be redone as Jon said.
> 
> > Alternatively, if the idea is to always print warnings, get rid of all
> > -W<option> flags, except for -Werror.
> 
> Not sure it's wanted behaviour, but I am in favour for anything that makes
> warning visible and not silently disappear.

Thinking more on this, I believe the -Wall must imply that any filters become
no-op.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Mauro Carvalho Chehab]

On Thu, Nov 06, 2025 at 09:31:40AM +0200, Andy Shevchenko wrote:
> On Wed, Nov 05, 2025 at 10:19:07PM +0100, Mauro Carvalho Chehab wrote:
> > Em Tue,  4 Nov 2025 22:55:02 +0100
> > Andy Shevchenko <andriy.shevchenko@linux.intel.com> escreveu:
> > 
> > > When kernel-doc parses the sections for the documentation some errors
> > > may occur. In many cases the warning is simply stored to the current
> > > "entry" object. However, in the most of such cases this object gets
> > > discarded and there is no way for the output engine to even know about
> > > that. To avoid that, check if the "entry" is going to be discarded and
> > > if there warnings have been collected, issue them to the current logger
> > > as is and then flush the "entry". This fixes the problem that original
> > > Perl implementation doesn't have.
> > > 
> > > As of Linux kernel v6.18-rc4 the reproducer can be:
> > > 
> > > $ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h
> > > ...
> > > Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr
> > > ...
> > > 
> > > while with the proposed change applied it gives one more line:
> > > 
> > > $ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h
> > > ...
> > > Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr
> > > Warning: include/linux/util_macros.h:144 expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead
> > > ...
> > > 
> > > And with the original Perl script:
> > > 
> > > $ scripts/kernel-doc.pl -v -none -Wall include/linux/util_macros.h
> > > ...
> > > include/linux/util_macros.h:139: info: Scanning doc for function to_user_ptr
> > > include/linux/util_macros.h:149: warning: expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead
> > > ...
> > > 
> > > Fixes: 9cbc2d3b137b ("scripts/kernel-doc.py: postpone warnings to the output plugin")
> > > Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> > > ---
> > >  scripts/lib/kdoc/kdoc_parser.py | 7 +++++++
> > >  1 file changed, 7 insertions(+)
> > > 
> > > diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> > > index ee1a4ea6e725..f7dbb0868367 100644
> > > --- a/scripts/lib/kdoc/kdoc_parser.py
> > > +++ b/scripts/lib/kdoc/kdoc_parser.py
> > > @@ -451,6 +451,13 @@ class KernelDoc:
> > >          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.entry = KernelEntry(self.config, self.fname, ln)
> > >  
> > >          # State flags
> > 
> > No objection of this one, but this breaks the behavior of the -W
> > flags.
> 
> Sorry for that, but at least now the outcome is much better than before.

That's why I said I'm not against ;-)

> 
> > See, the way kernel-doc.pl worked is that:
> > 
> > 1. Warnings are controlled via several -W flags:
> > 
> >   -Wreturn, --wreturn   Warns about the lack of a return markup on functions.
> >   -Wshort-desc, -Wshort-description, --wshort-desc
> >                         Warns if initial short description is missing
> > 
> >                         This option is kept just for backward-compatibility, but it does nothing,
> >                         neither here nor at the original Perl script.
> >   -Wall, --wall         Enable all types of warnings
> >   -Werror, --werror     Treat warnings as errors.
> > 
> >   Those affect running kernel-doc manually.
> > 
> > 2. Warnings are affected by the filtering commands:
> > 
> >   -e, -export, --export
> >                         
> >                         Only output documentation for the symbols that have been
> >                         exported using EXPORT_SYMBOL() and related macros in any input
> >                         FILE or -export-file FILE.
> >   -i, -internal, --internal
> >                         
> >                         Only output documentation for the symbols that have NOT been
> >                         exported using EXPORT_SYMBOL() and related macros in any input
> >                         FILE or -export-file FILE.
> >   -s, -function, --symbol SYMBOL
> >                         
> >                         Only output documentation for the given function or DOC: section
> >                         title. All other functions and DOC: sections are ignored.
> >                         
> >                         May be used multiple times.
> > 
> > 
> >   Those affect both running kernel-doc manually or when called via make htmldocs,
> >   as the kerneldoc Sphinx markup supports them.
> > 
> > As the filters are only applied at kdoc/kdoc_output.py, printing warnings
> > early at kdoc_parser means that, even ignored symbols will be warned.
> 
> Maybe I failed to make the point of the reproducer. The kernel doc and prototype
> are mismatched, and hence there is no way one may filter this in accordance
> with the logic I read.

I see.

> These warnings must be printed independently on the
> filters as filters may not be applied to this. Or i.o.w. what has one to put to
> -s for the reproducer case to make it visible? Also what should one put to make
> it on par with the previous behaviour?

FYI, I'm not a big fan of warning suppression. I only implemented the
-W flags on Python after implementing all other functionalities.

I did it mostly because I wanted to be bug-compatible with the perl
version. Heh, even on the perl version, one of the -W flags weren't
used.

> 
> > It might
> > also make the same warning to appear more than once, for C files that are listed
> > on multiple kerneldoc entries(*).
> > 
> > (*) There is a logic at kerneldoc.py Sphinx extension and inside kdoc_files
> >     to avoid parsing the same file twice, but I didn't test adding a hack
> >     similar to this one to double-check that the warning won't appear multiple
> >     times when export is used. Maybe it is working fine.
> > 
> > -
> > 
> > In summary, if warnings are suppressed, my suggestion would be to check at 
> > kdoc_output to see what is filtering them out. 
> 
> In the commit message I tried to explain the situation. These warning are
> vanished _before any_ output plugin is run. There is *no way* to get them
> printed otherwise.  It's, of course, possible that I haven't got deeply the
> idea behind architecture of the logging in the Python script. I am all ears for
> the improvements that satisfy everybody.
> 
> I think the problem is in design, it needs to be redone as Jon said.

Originally, the warning function were just printing all warnings there
directly. After I finished the script, I had to move them to be shown
after filtering, in order to reproduce the same behavior of the -W flags.

If we get rid of them (your patch effectively did that), we can just
simplify the warning function and drop the prints from the output module.

From my side, IMO this is the best alternative.

> > Alternatively, if the idea is to always print warnings, get rid of all
> > -W<option> flags, except for -Werror.
> 
> Not sure it's wanted behaviour, but I am in favour for anything that makes
> warning visible and not silently disappear.
> 
> -- 
> With Best Regards,
> Andy Shevchenko
> 
> 

-- 
Thanks,
Mauro

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Randy Dunlap]

On 11/5/25 10:12 AM, Jonathan Corbet wrote:
> [Heads up to Stephen: this change will add a bunch of warnings that had
> been dropped before.]
> 
> Andy Shevchenko <andriy.shevchenko@linux.intel.com> writes:
> 
>> When kernel-doc parses the sections for the documentation some errors
>> may occur. In many cases the warning is simply stored to the current
>> "entry" object. However, in the most of such cases this object gets
>> discarded and there is no way for the output engine to even know about
>> that. To avoid that, check if the "entry" is going to be discarded and
>> if there warnings have been collected, issue them to the current logger
>> as is and then flush the "entry". This fixes the problem that original
>> Perl implementation doesn't have.
> 
> I would really like to redo how some of that logging is done, but that
> is an exercise for another day.  For now, I have applied this one,
> thanks.

I think that this patch is causing a (large) problem.

With this patch:
$ make mandocs &>mandocs.out

Without this patch:
$ make mandocs &>mandocsnoas.out

$ wc mandocs.out mandocsnoas.out
  29544  267393 3229456 mandocs.out
  10052   95948 1208101 mandocsnoas.out

so it appears that this patch causes lots of extra output.
Some of that may be what the patch was trying to do, but
with this patch, "mandocs.out" above has lots of duplicated
Warning: lines.

$ sort mandocs.out | uniq > mandocsuq.out
$ wc mandocsuq.out
  18012  167689 1994145 mandocsuq.out

$ grep -c "^Warning:"  mandocs.out mandocsnoas.out  mandocsuq.out 
mandocs.out:25273
mandocsnoas.out:10022
mandocsuq.out:15252


In mandocs.out above (29544 lines), this line:
Warning: ../sound/soc/sprd/sprd-mcdt.h:48 struct member 'dma_chan' not described in 'sprd_mcdt_chan'

is found at lines 7 and 29122.

So maybe the logging output needs to be repaired sooner
than later.

-- 
~Randy

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Andy Shevchenko]

On Sat, Nov 08, 2025 at 04:03:15PM -0800, Randy Dunlap wrote:
> On 11/5/25 10:12 AM, Jonathan Corbet wrote:
> > [Heads up to Stephen: this change will add a bunch of warnings that had
> > been dropped before.]
> > Andy Shevchenko <andriy.shevchenko@linux.intel.com> writes:
> > 
> >> When kernel-doc parses the sections for the documentation some errors
> >> may occur. In many cases the warning is simply stored to the current
> >> "entry" object. However, in the most of such cases this object gets
> >> discarded and there is no way for the output engine to even know about
> >> that. To avoid that, check if the "entry" is going to be discarded and
> >> if there warnings have been collected, issue them to the current logger
> >> as is and then flush the "entry". This fixes the problem that original
> >> Perl implementation doesn't have.
> > 
> > I would really like to redo how some of that logging is done, but that
> > is an exercise for another day.  For now, I have applied this one,
> > thanks.
> 
> I think that this patch is causing a (large) problem.
> 
> With this patch:
> $ make mandocs &>mandocs.out
> 
> Without this patch:
> $ make mandocs &>mandocsnoas.out
> 
> $ wc mandocs.out mandocsnoas.out
>   29544  267393 3229456 mandocs.out
>   10052   95948 1208101 mandocsnoas.out
> 
> so it appears that this patch causes lots of extra output.
> Some of that may be what the patch was trying to do, but
> with this patch, "mandocs.out" above has lots of duplicated
> Warning: lines.
> 
> $ sort mandocs.out | uniq > mandocsuq.out
> $ wc mandocsuq.out
>   18012  167689 1994145 mandocsuq.out
> 
> $ grep -c "^Warning:"  mandocs.out mandocsnoas.out  mandocsuq.out 
> mandocs.out:25273
> mandocsnoas.out:10022
> mandocsuq.out:15252

Yes, that's what Mauro explained, that we may have the dups.

> In mandocs.out above (29544 lines), this line:
> Warning: ../sound/soc/sprd/sprd-mcdt.h:48 struct member 'dma_chan' not described in 'sprd_mcdt_chan'
> 
> is found at lines 7 and 29122.
> 
> So maybe the logging output needs to be repaired sooner
> than later.

Right! But I'm not familiar with this, so I can help only with testing,
and not with real fix development.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently discarded

[Randy Dunlap]

On 11/9/25 7:54 AM, Andy Shevchenko wrote:
> On Sat, Nov 08, 2025 at 04:03:15PM -0800, Randy Dunlap wrote:
>> On 11/5/25 10:12 AM, Jonathan Corbet wrote:
>>> [Heads up to Stephen: this change will add a bunch of warnings that had
>>> been dropped before.]
>>> Andy Shevchenko <andriy.shevchenko@linux.intel.com> writes:
>>>
>>>> When kernel-doc parses the sections for the documentation some errors
>>>> may occur. In many cases the warning is simply stored to the current
>>>> "entry" object. However, in the most of such cases this object gets
>>>> discarded and there is no way for the output engine to even know about
>>>> that. To avoid that, check if the "entry" is going to be discarded and
>>>> if there warnings have been collected, issue them to the current logger
>>>> as is and then flush the "entry". This fixes the problem that original
>>>> Perl implementation doesn't have.
>>>
>>> I would really like to redo how some of that logging is done, but that
>>> is an exercise for another day.  For now, I have applied this one,
>>> thanks.
>>
>> I think that this patch is causing a (large) problem.
>>
>> With this patch:
>> $ make mandocs &>mandocs.out
>>
>> Without this patch:
>> $ make mandocs &>mandocsnoas.out
>>
>> $ wc mandocs.out mandocsnoas.out
>>   29544  267393 3229456 mandocs.out
>>   10052   95948 1208101 mandocsnoas.out
>>
>> so it appears that this patch causes lots of extra output.
>> Some of that may be what the patch was trying to do, but
>> with this patch, "mandocs.out" above has lots of duplicated
>> Warning: lines.
>>
>> $ sort mandocs.out | uniq > mandocsuq.out
>> $ wc mandocsuq.out
>>   18012  167689 1994145 mandocsuq.out
>>
>> $ grep -c "^Warning:"  mandocs.out mandocsnoas.out  mandocsuq.out 
>> mandocs.out:25273
>> mandocsnoas.out:10022
>> mandocsuq.out:15252
> 
> Yes, that's what Mauro explained, that we may have the dups.

OK, I remember something about that...

>> In mandocs.out above (29544 lines), this line:
>> Warning: ../sound/soc/sprd/sprd-mcdt.h:48 struct member 'dma_chan' not described in 'sprd_mcdt_chan'
>>
>> is found at lines 7 and 29122.
>>
>> So maybe the logging output needs to be repaired sooner
>> than later.
> 
> Right! But I'm not familiar with this, so I can help only with testing,
> and not with real fix development.

Same for me.

Thanks.
-- 
~Randy