Re: API Documentation Coverage
- From: Keith Sharp <kms passback co uk>
- To: Malcolm Tredinnick <malcolm commsecure com au>
- Cc: gnome-doc-list gnome org
- Subject: Re: API Documentation Coverage
- Date: Mon, 05 Apr 2004 09:41:38 +0100
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
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
Good point on the short/long descriptions, I'll have a look into
> 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. :)
] [Thread Prev