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

[Randy Dunlap <rdunlap@infradead.org>]

[-- Attachment #1: Type: text/plain, Size: 3172 bytes --]



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?

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

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.

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.

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.

FWIW.
-- 
~Randy

[-- Attachment #2: kerndoc-export-search.pl --]
[-- Type: application/x-perl, Size: 13692 bytes --]