On 8/31/25 1:16 PM, Jonathan Corbet wrote: > Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> 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:
kerndoc-export-search.pl
Description: Perl program
