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.
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?
rday
--
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================
--
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
