Message-ID: <aQxO3MaDwFrIwCV0@smile.fi.intel.com>
Date: Thu, 6 Nov 2025 09:31:40 +0200
From: Andy Shevchenko <andriy.shevchenko@...ux.intel.com>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org,
	linux-kernel@...r.kernel.org
Subject: Re: [PATCH v1 1/1] kernel-doc: Issue warnings that were silently
 discarded

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@...ux.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@...ux.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

Powered by blists - more mailing lists