Re: API Documentation Coverage

[Malcolm Tredinnick <malcolm commsecure com au>]

On Sun, 2004-04-04 at 19:52 +0100, Keith Sharp wrote:
> On Thu, 2004-04-01 at 10:20, Keith Sharp wrote:
> > Hello,
> > 
> > I seem to recall that there was a table which indicated the completeness
> > of API documents for the different GNOME libraries.  Does this still
> > exist and is just cunningly hidden from me?  Could it be returned to
> > life if it has died?
> 
> I spoke to Shaun on IRC and he hopes to be able to resurrect this as
> part of his new gnome-doc-utils package.
> 
> In the meantime I finally got jhbuild to complete (apart from
> gnomemeeting) and I ran a script to analyse the build logs.  From this I
> was able to extract the following:

[...snip...]

One trap with the output of gtk-doc: the *-undocumented.txt files do not
take into account any entries in *-unused.txt. Many packages that have
been in use for a while and have subsequently had API additions (even
signals or properties) will have lines in the 'unused' file that need to
be manually added to *-sections.txt.

So if you want more accurate descriptions, you should consider adding
the number of entries in *-unused to the number of undocumented entries.
Many of them will instantly become 'documented' when added to
*-sections.txt, but for the time being they are undocumented, since they
do not appear in the produced HTML pages. For bonus points, you can also
look inside tmpl/*.sgml and report on any pages that don't have a short
description or long description, since they do not show up
automatically.

On a more positive note, some kind of automated "how up to date are we"
report for the API docs would be a good idea.

Nice stuff. :)

Cheers,
Malcolm