diff options
| author | Andy Shevchenko <andriy.shevchenko@linux.intel.com> | 2025-11-04 22:55:02 +0100 |
|---|---|---|
| committer | Jonathan Corbet <corbet@lwn.net> | 2025-11-05 11:05:37 -0700 |
| commit | 469c1c9eb6c9243e4b59ef93518d4e0acb1b2b3e (patch) | |
| tree | f2dc3394a86f8b3843fe30b41fbca031df5a4e32 /scripts | |
| parent | 27600b51fbc8b9a4eba18c8d88d7edb146605f3f (diff) | |
kernel-doc: Issue warnings that were silently discarded
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>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251104215502.1049817-1-andriy.shevchenko@linux.intel.com>
Diffstat (limited to 'scripts')
| -rw-r--r-- | scripts/lib/kdoc/kdoc_parser.py | 7 |
1 files changed, 7 insertions, 0 deletions
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 |