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

[Andy Shevchenko <andriy.shevchenko@linux.intel.com>]

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