Re: API Documentation Coverage

[Keith Sharp <kms passback co uk>]

On Mon, 2004-04-05 at 03:24, Malcolm Tredinnick wrote:
>
> 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.

I wasn't sure if a declaration being in the *-unused.txt file was
intentional or not.  I thought that in some cases the developer may have
decided that a particular declaration should not be documented, so they
did not include it in the *-sections.txt file.  Is this ever the case or
should all declarations in the *-unused.txt and *-undocumented.txt be
properly documented?

I must confess to being a complete newbie at gtk-doc.  I guess that a
good project for someone getting interested in API docs would be to
document gtk-doc properly :-)

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

Good point on the short/long descriptions, I'll have a look into
including that.

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

That is where I started from.  The only problem I can see is that to do
the sort of thing I did you need to get the system to build from CVS -
and running jhbuild against anoncvs is painful, it took me three days
because of projects with only partial updates causing failed builds etc
etc.  (Missing mkinstalldirs is a pain as well).

> Nice stuff. :)

Thanks,

Keith.