Em Sun, 31 Aug 2025 23:17:22 -0700 Randy Dunlap <rdunlap@xxxxxxxxxxxxx> escreveu: > 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? 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
