Re: couple questions about kerneldoc

"Robert P. J. Day" <rpjday@xxxxxxxxxxxxxx> · Fri, 31 Aug 2012 14:22:39 -0400 (EDT)

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)
are enclosed in an XML comment.  so what's the rationale behind that
leading "X"?  tradition?  since it certainly doesn't seem to processed
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?

> >   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.