On Fri, 26 Aug 2016, Mauro Carvalho Chehab <mche...@s-opensource.com> wrote: > Em Fri, 26 Aug 2016 11:34:38 +0200 > Markus Heiser <markus.hei...@darmarit.de> escreveu: > >> Am 23.08.2016 um 16:43 schrieb Mauro Carvalho Chehab >> <mche...@s-opensource.com>: >> >> > Em Mon, 22 Aug 2016 14:57:40 -0600 >> > Jonathan Corbet <cor...@lwn.net> escreveu: >> > >> >> This short series convers device-drivers.tmpl into the RST format, splits >> >> it up, and sets up the result under Documentation/driver-api/. For added >> >> fun, I've taken one top-level file (hsi.txt) and folded it into the >> >> document as a way of showing the direction I'm thinking I would like >> >> things >> >> to go. There is plenty more of this sort of work that could be done, to >> >> say the least - this is just a beginning! >> >> >> >> The formatted results can be seen at: >> >> >> >> http://static.lwn.net/kerneldoc/driver-api/index.html >> > >> > Thanks for doing that! IMHO, the conversion of this book is indeed >> > one of the first things to be done. >> >> >> As part of the long-term task to turn Documentation/ into less of a horror >> >> movie, I'd like to collect documentation of the driver-specific API here. >> >> >> >> Hi, >> >> here are my 2cent, about the *generic* content from the kernel-doc >> directive: >> >> .. kernel-doc:: kernel/sched/core.c >> :export: >> >> IMHO directives like the one above are to *generic*. If I read this directive >> I would expect, that all exported symbols are documented. But this is a false >> estimation! >> >> In my POC I use a more restrictive kernel-doc parser >> (https://github.com/return42/linuxdoc). For the directive above the parser >> logs, that some of the exported symbols are not found / not documented: >> >> $ kernel-doc --quiet --list-exports kernel/sched/core.c >> [exported undocumented ] set_cpus_allowed_ptr >> [exported undocumented ] kick_process >> [exported function ] wake_up_process >> [exported undocumented ] preempt_notifier_inc >> [exported undocumented ] preempt_notifier_dec >> [exported function ] preempt_notifier_register >> [exported function ] preempt_notifier_unregister >> [exported undocumented ] single_task_running >> [exported undocumented ] preempt_count_add >> [exported undocumented ] preempt_count_sub >> [exported undocumented ] schedule >> [exported undocumented ] preempt_schedule >> [exported function ] preempt_schedule_notrace >> [exported undocumented ] default_wake_function >> [exported undocumented ] set_user_nice >> [exported function ] sched_setscheduler >> [exported undocumented ] sched_setattr >> [exported function ] sched_setscheduler_nocheck >> [exported undocumented ] _cond_resched >> [exported undocumented ] __cond_resched_lock >> [exported undocumented ] __cond_resched_softirq >> [exported function ] yield >> [exported function ] yield_to >> [exported undocumented ] io_schedule_timeout >> [exported undocumented ] __might_sleep >> [exported undocumented ] ___might_sleep >> >> >> The driver-api is full of *generic* content and IMHO it is not really clear >> what would be a part of the resulting documentation. To illustrate, you >> can take a look on the (old) *automatic* conversion of mine at: >> >> http://return42.github.io/sphkerneldoc/books/device-drivers/index.html >> >> There you see a list of 'Oops: Document generation inconsistency.' >> This kind of missing documentation grows up with changes to >> the source files while there are no errors reported. >> >> What I mean: in most use cases it is better to be explicit and name the >> functions, structs or whatever which should be a part of the documentation. >> e.g.:: >> >> .. kernel-doc:: kernel/sched/core.c >> :functions: wake_up_process yield ... >> >> By being explicit, the kernel-doc parser has a chance to identify requested >> but missing documentation and log related error messages. >> >> Summarized: >> >> - *explicit* is better than implicit. >> - the *generic* part of kernel-doc parser should more restrictive >> >> These are my thoughts, even if we do nothing to handle it, we >> should aware about this. > > I actually prefer the opposite:
Ditto. Jani. > > - on a *.c file, it should assume that *all* exported symbols should be > documented (either at the C code itself or at a header file); > > - on a *.h file, it should assume that *all* structs, enums, typedefs, > function prototypes and static inline functions should be documented. > As I stated before, we should also add a way to document defines. > Assuming that we add such way, for defines, it should implicitly > ignore the ones used inside the header to enable/disable part of > its contents, like: > #define _FOO_H_ > #ifndef _FOO_H_ > .... > #endif > > Then, add an option to allow explicitly ignoring symbols. The lack > of documentation for a symbol that matches the above criteria and > isn't explicitly ignored should be warned, as this is a documentation > gap that should be fixed. > > Thanks, > Mauro -- Jani Nikula, Intel Open Source Technology Center
