On 08/31/2012 11:22 AM, Robert P. J. Day wrote:
> On Fri, 31 Aug 2012, Randy Dunlap wrote:
>
>> On 08/31/2012 05:45 AM, Robert P. J. Day wrote:
>>>
>>> <!-- FIXME: Removed for now since no structured comments in source
>>> <sect1><title>Wireless</title>
>>> X!Enet/core/wireless.c
>>> </sect1>
>>> -->
>>>
>>> is that just a way of commenting out a kerneldoc directive? if so,
>>> the surrounding XML comment would seem to be superfluous, unless "X"
>>> does something different.
>>
>> AFAICT, the XML comment is sufficient.
>>
>> scripts/docproc.c handles these:
>> * 1) Lines containing !E
>> * 2) Lines containing !I
>> * 3) Lines containing !D
>> * 4) Lines containing !F
>> * 5) Lines containing !P
>> * 6) Lines containing !C
>
> so just to be clear, there's nothing at all magical about that "X"
> prefix, right? every example of that i've seen (and there are many)
right.
> are enclosed in an XML comment. so what's the rationale behind that
> leading "X"? tradition? since it certainly doesn't seem to processed
no idea. I don't know who introduced it in the one file where
it is used.
> by kernel-doc. in fact, if you add a leading "X" to a kernel-doc
> directive, you get that directive printed out verbatim in the output.
> in short, it's treated as simple text.
> so where did that tradition come from?
Only way to find out is to find the patch that added it, I guess.
>>> also, in explanation file kernel-doc-nano-HOWTO.txt, we read the
>>> explanation about the .tmpl file prefixes:
>>>
>>> ... snip ...
>>> !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.
>>> ... snip ...
>>>
>>> first, how does "!D" differ from "!E", it's not clear from the
>>> above. also, it seems that "!D" is broken anyway, from that same
>>> networking.tmpl file:
>>>
>>> <!-- The !D functionality is not perfect, garbage has to be protected by comments
>>> !Dnet/sunrpc/sunrpc_syms.c
>>> -->
>>>
>>> if "!D" doesn't work, that should be clear, don't you think?
>>
>> Sure, or fixed or even deleted since nothing is currently using !D
>> AFAICT.
>
> given that there's only one usage of it in the entirety of the
> DocBook/ directory, it would be trivially easy to remove that and it's
> processing from docproc.c unless it's meant to have some value and
> just isn't currently implemented properly. what is it *supposed* to
> do? here's the code:
>
> switch (line[1]) {
> case 'E':
> while (*s && !isspace(*s)) s++;
> *s = '\0';
> externalfunctions(line+2);
> break;
> case 'I':
> while (*s && !isspace(*s)) s++;
> *s = '\0';
> internalfunctions(line+2);
> break;
> case 'D':
> while (*s && !isspace(*s)) s++;
> *s = '\0';
> symbolsonly(line+2);
> break;
>
> so the difference between 'E' and 'D' is externalfunctions() versus
> symbolsonly(). which means what? and is it worth keeping and fixing,
> or just tossing?
>
> oh, wait, from the main() routine, there is apparently no difference
> whatever:
>
> /* Collect symbols */
> defaultline = noaction;
> internalfunctions = find_export_symbols;
> externalfunctions = find_export_symbols;
> symbolsonly = find_export_symbols;
>
> i vote for tossing.
>
> more kernel-doc questions shortly.
>
> rday
>
--
~Randy
--
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
