On 07/26/2013 06:21:55 AM, Robert P. J. Day wrote:
On Thu, 25 Jul 2013, Rob Landley wrote:
> > 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?
It pulls in kernel-doc content from files and intersperses it with
docbook chunks contained in the template. Nothing says you have to
can't have a chunk of documentation in the template explaining a
section of code you don't feel like marking up. There's potential
version skew if the code changes, of course...
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.
If you want to describe the wake_up_* macros in the device drivers
manual, and don't want to mark up said macros and include them, then
your other option is to add a chunk of docbook to the device drivers
template describing the wake_up macros.
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
