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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

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