a collection of observations from the last day or so ...
first, the howto for kernel-doc *really* stresses to not leave a
blank line after the opening function name:
"Avoid putting a spurious blank line after the function name, or else
the description will be repeated!"
but i just tried that and it seems to work fine -- perhaps someone
tweaked the build process to handle this? if that's the case, that
emphatic warning could probably be toned down. :-) in any event, blank
lines don't appear to cause a problem (anymore?).
(ASIDE: an actual *blank* line would cause problems, but an
additional blank *comment* line seems to be fine.)
next, i just noticed how one comments out directives, like this in
networking.tmpl:
<!-- FIXME: Removed for now since no structured comments in source
<sect1><title>Wireless</title>
X!Enet/core/wireless.c
</sect1>
-->
so in addition to the surrounding comment, you still need to
deactivate each enclosed kernel-doc directive; in this case, with a
leading "X" (any other character would work just as well, "X" is just
a convention?)
next, in kernel-doc-nano-HOWTO.txt, one reads about the "!E"
directive:
"!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 understand the second part of that sentence -- what exactly
is being collected from the Makefile? what "files" listed in the
Makefile is this talking about?
moving on, what is the current status of "!D"? first, the
explanation is confusing:
"!D<filename> is used to name additional files to search for functions
exported using EXPORT_SYMBOL."
it's not at all clear how that's supposed to differ from "!E". in
addition, the only usage of it is here in networking.tmpl:
</sect1>
<sect1><title>SUN RPC subsystem</title>
<!-- The !D functionality is not perfect, garbage has to be protected by comments
!Dnet/sunrpc/sunrpc_syms.c
-->
and, from memory, that warning has been there a long time, so either
!D should be fixed (to do whatever the heck it's supposed to do), or
it should be tossed, no?
i think that's it for now ...
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
