[Ksummit-discuss] [CORE-TOPIC] Documentation

[Mauro Carvalho Chehab]

Em Sun, 12 Jul 2015 19:15:32 -0400 (EDT)
Julia Lawall <julia.lawall at lip6.fr> escreveu:

> > So this leads me to following questions:
> > - How can we easily identify missing documentation?
> > -- Maybe Julia can come up with some coccinelle magic?
> > -- Maybe even mark non-extractable documentation and convert it.
> > -- In the document it mentions scripts/basic/doproc.c checks for missing
> > documentation, but this file does not exist anymore :/
> 
> Interesting idea.  I had not thought of this.  Coccinelle doesn't really
> process comments, but one can always use grep.  So the idea would be to
> find function definitions that don't have anything that looks like a
> comment in the lines above (ie, the lines since the end of the previous
> function definition).  One could furthermore rank the results by the
> number of non-local calls to the function.  I guess there would be a lot
> of reports, and it would be most productive to start with functions that
> are commonly used,

I guess it should first try to classify the type of the exported symbols,
in order to check either if they're used only internally inside a subsystem or
global wide, and report, by default, just the global wide undocumented ones,
sorted by number of occurrences.

Maybe the tool could be based on LXR[1] or use some output of it.

[1] http://free-electrons.com/pub/source/lxr-0.3.1-fe1.tar.bz2

Regards,
Mauro