the kernel-doc nano HOWTO could also be spruced up a bit. after
some goofing around, here's what i think i've discovered based on this
final part of the help file:
... snip ...
How to make new SGML template files
-----------------------------------
SGML template files (*.tmpl) are like normal SGML files, except that
they can contain escape sequences where extracted documentation should
be inserted.
!E<filename> is replaced by the documentation, in <filename>, for
functions that are exported using EXPORT_SYMBOL: the function list is
collected from files listed in Documentation/DocBook/Makefile.
!I<filename> is replaced by the documentation for functions that are
_not_ exported using EXPORT_SYMBOL.
!D<filename> is used to name additional files to search for functions
exported using EXPORT_SYMBOL.
!F<filename> <function [functions...]> is replaced by the
documentation, in <filename>, for the functions listed.
!P<filename> <section title> is replaced by the contents of the DOC:
section titled <section title> from <filename>.
Spaces are allowed in <section title>; do not quote the <section
title>.
!C<filename> is replaced by nothing, but makes the tools check that
all DOC: sections and documented functions, symbols, etc. are used.
This makes sense to use when you use !F/!P only and want to verify
that all documentation is included.
... end ...
1) as mentioned earlier, it looks like that "!D" code can be tossed
entirely since it appears to contribute nothing different from "!E",
but i'm willing to be persuaded otherwise.
2) all of those rules refer solely to "functions", which is misleading
-- it should be noted that they refer to the totality of functions,
structs, unions, typedefs and enums, no?
3) the reference(s) to EXPORT_SYMBOL should be expanded to refer to
all of EXPORT_SYMBOL, EXPORT_SYMBOL_GPL and EXPORT_SYMBOL_GPL_FUTURE,
no? that's how i read docproc.c.
4) it might be worth mentioning that any function/struct/union/etc can
be addressed at most once; otherwise, bad things happen. just for
fun, to test referring to a function, i added its reference below a
kernel-doc directive for the entire file it was contained in, so that
it would have been processed twice. that didn't work. i have no
problem with that, it should probably just be mentioned.
any other annoying pedantry i'm overlooking?
rday
p.s. oh, wait, there's this:
"!E<filename> is replaced by the documentation, in <filename>, for
functions that are exported using EXPORT_SYMBOL: the function list is
collected from files listed in Documentation/DocBook/Makefile."
i don't know what that last part means:
"... the function list is collected from files listed in
Documentation/DocBook/Makefile."
am i just being clueless in not understanding that?
--
========================================================================
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
