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

[Randy Dunlap <rdunlap@infradead.org>]

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