On Thu, 25 Jul 2013, Rob Landley wrote:
> 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?
maybe i'm missing something, but as i read it, scsi.tmpl still pulls
in the kernel-doc content from various files, so wouldn't you still
need to add that content? or am i misunderstanding something?
anyway, as i'm sure you see, my major point is that while i would
dearly love things like the "wake_up_*" macros to be part of the
device drivers manual, even *i'm* not sure i can justify adding
several lines of kernel-doc content for each single line of macro
definition, regardless of how informative that would be.
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
