Re: [TECH TOPIC] Kernel documentation - update and future directions

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

Em Sun, 31 Aug 2025 23:17:22 -0700
Randy Dunlap <rdunlap@infradead.org> escreveu:

> On 8/31/25 1:16 PM, Jonathan Corbet wrote:
> > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> >   
> >> 4) kernel-doc kAPI
> >>
> >> It shouldn't be that hard to do the same for kernel-doc kAPI documentation:
> >> kernel-doc now can parse the entire tree with:
> >>
> >> 	$ scripts/kernel-doc .
> >>
> >> Someone can easily use it to discover the current gaps at the docs that
> >> have already some kernel-doc markups and identify what of them aren't
> >> yet placed under Documentation/ ".. kernel-doc::" markups.  
> 
> Mauro, I tried that for one file: kernel/audit.c
> but didn't see what I expected to see.
> What options should I be using to find the gaps?

If you want to check all warnings kernel-doc detect, use -Wall:

	$ ./scripts/kernel-doc -Wall kernel/audit.c --none
	Warning: kernel/audit.c:216 No description found for return value of 'auditd_test_task'
	Warning: kernel/audit.c:254 No description found for return value of 'audit_ctl_owner_current'
	Warning: kernel/audit.c:265 No description found for return value of 'auditd_pid_vnr'
	Warning: kernel/audit.c:289 No description found for return value of 'audit_get_sk'
	Warning: kernel/audit.c:498 No description found for return value of 'auditd_set'
	Warning: kernel/audit.c:687 No description found for return value of 'auditd_send_unicast_skb'
	Warning: kernel/audit.c:747 No description found for return value of 'kauditd_send_queue'
	Warning: kernel/audit.c:841 No description found for return value of 'kauditd_thread'
	Warning: kernel/audit.c:1828 No description found for return value of 'audit_serial'
	Warning: kernel/audit.c:1860 No description found for return value of 'audit_log_start'
	Warning: kernel/audit.c:1937 No description found for return value of 'audit_expand'
	Warning: kernel/audit.c:2093 No description found for return value of 'audit_string_contains_control'
	Warning: kernel/audit.c:2359 No description found for return value of 'audit_set_loginuid'
	Warning: kernel/audit.c:2394 No description found for return value of 'audit_signal_info'

To be bug-compatible with the Perl version, I ported -Wall to it,
as otherwise there would be tons of extra warnings after migration.

Ok, it doesn't tell that there are exports there, although kernel-doc
knows, as it has to process exports anyway.

> > ...or one can use scripts/find-unused-docs.sh, which was written for
> > just this purpose :)  

It should be very easy to add an option to kernel-doc to do the same.

IMO, reducing the number of scripts may help people to better use
the tools.

> 
> Yes, and I have used this script. It does what it was meant to do AFAIK.
> It's reporting is at a gross file level.
> 
> I made a small subdirectory called "test" and copied kernel/audit.c to test/.
> 
> $ ./scripts/find-unused-docs.sh  test/
> The following files contain kerneldoc comments for exported functions that are not used in the formatted documentation
> test/audit.c
> 
> Sometime in the last 2-3 years Matthew Wilcox asked me about a tool (script, whatever)that would detect both EXPORTs without kernel-doc and kernel-doc without EXPORTs.
> Either one of these can be noisy (with false positives) and they often don't lend
> themselves to easy/beginner fixes.

Heh, not knowing/remembering about find-unused-docs.sh, I actually
wrote a prototype for something similar sometime ago, in Perl.
Didn't upstream it though, nor used it much as I got sidetracked
by other things. My goal on that time were to find gaps on media kAPI.

> Anyway, after some delay, I have such a script. It's written in Perl (I started
> on it over a year ago!). It might have been desirable to add it to scripts/kernel-doc.pl
> at the time, but it didn't seem to me like a good fit there, so it's independent.
> 
> Running (no options, just produce a summary)
> $ kerndoc-export-search.pl test/audit.c
> reports:
> Missing kernel-doc for: audit_log_task_info
> Missing kernel-doc for: audit_enabled
> Missing kernel-doc for: audit_log_task_context
> 3 missing kernel-docs
> Missing EXPORT for: audit_serial
> Missing EXPORT for: audit_log_untrustedstring
> Missing EXPORT for: audit_log_n_untrustedstring
> Missing EXPORT for: audit_log_n_hex
> Missing EXPORT for: audit_log_lost
> Missing EXPORT for: audit_set_loginuid
> Missing EXPORT for: auditd_test_task
> Missing EXPORT for: audit_ctl_lock
> Missing EXPORT for: audit_string_contains_control
> Missing EXPORT for: audit_signal_info
> Missing EXPORT for: audit_log_path_denied
> Missing EXPORT for: audit_ctl_unlock
> 12 missing Exports
> 
> If that's not verbose enough (!), the -l (list) option lists each function's
> location and short description. One example:
> test/audit.c: 2006: audit_log_format:  * audit_log_format - format a message into the audit buffer.

Nice! Yet, I suggest trying to merge with kernel-doc, even if the
actual implementation would be on a separate class inside a
separate file.

Still, the way kernel-doc works allow one to just write a different
output class (or improve the output class used by --none) to use
the already parsed data on different ways.

> But that generates lots of output.
> 
> And of course, for function, I mean function/struct/union/enum/typedef.
> 
> There is a "verbose" option but it currently does not print anything.
> 
> Here is a help summary:
> $ kerndoc-export-search.pl -h
> kerndoc-export-search.pl [--list|-l] [--verbose|-v] file(s)
>   where --list    prints filename:line:funcname: short_description
>   where --verbose prints more info.
>   default: prints a doc/export summary + warnings.
>   version: 0.9
> 
> 
> Feel free to use in any way or to rewrite & merge it into the
> kdoc python system.

Good to know! I'll try to take a look on it later on.

Thanks,
Mauro