On 07/19/2013 07:07:36 AM, Robert P. J. Day wrote:
more a philosophical question but it seems there are pretty major
gaps in what gets kerneldoc'ed although i'm not sure what to do about
it.
There are pretty major gaps in what gets documented period.
case in point: when one builds the device-drivers manual with "make
htmldocs", there's a section on "Wait queues and Wake events". fair
enough, but what's documented is almost entirely the "wait_" routines
-- only at the very bottom are there links to just two "wake_up"
routines, wake_up_bit and wake_up_atomic_t, which aren't even that
important.
if you look in wait.h, you can see all the important wake routines:
#define wake_up(x) __wake_up(x, TASK_NORMAL, 1,
NULL)
#define wake_up_nr(x, nr) __wake_up(x, TASK_NORMAL, nr,
NULL)
#define wake_up_all(x) __wake_up(x, TASK_NORMAL, 0,
NULL)
#define wake_up_locked(x) __wake_up_locked((x),
TASK_NORMAL, 1)
#define wake_up_all_locked(x) __wake_up_locked((x),
TASK_NORMAL, 0)
#define wake_up_interruptible(x) __wake_up(x,
TASK_INTERRUPTIBLE, 1, NULL)
#define wake_up_interruptible_nr(x, nr) __wake_up(x,
TASK_INTERRUPTIBLE, nr, NULL)
#define wake_up_interruptible_all(x) __wake_up(x,
TASK_INTERRUPTIBLE, 0, NULL)
#define wake_up_interruptible_sync(x) __wake_up_sync((x),
TASK_INTERRUPTIBLE, 1)
... etc etc ...
since none of those have associated kernel-doc content, they obviously
won't show up in a manual, but they're clearly important for
programming. on the other hand, adding kernel-doc content to every one
of those macros would be (IMHO) massive overkill.
so what's the solution here? it seems silly to add 10 lines of
kernel-doc for one line of macro, but what other choice is there if
those calls should be documented?
Write docbook lumps ala Documentatino/DocBook/scsi.tmpl describing them?
The downside is they get out of sync if the code changes, but that's
true of any non-inline solution. And it only really makes sense to do
this as docbook instead of a textfile if you're going to be importing
other files, so the logical place for it would be the Device Driver
manual wrapper that's pulling in the other files...
That's my guess anyway, but I'm still a week or so behind on the list
so there are probably other/better answers by now. :)
Rob--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
