Re: API Documentation Coverage

[Malcolm Tredinnick <malcolm commsecure com au>]

Hi Keith,

On Mon, 2004-04-05 at 09:41 +0100, Keith Sharp wrote:
> 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?

Not everything needs to be documented. One consequence of the kind of
"object oriented" C we use in GObject, GLib, GTK+, etc, is that there
are a number of functions that appear time and again for each object.
For example, an object called Foo will usually have a function
foo_get_type() that is completely uninteresting to users of class Foo
(most of the time), but is a public function because it is needed
sometimes. In order to avoid having to document these 'boring'
functions, the *-sections.txt file contains (in amongst the
<SECTION>...</SECTION> groups), subsections call <SUBSECTION Private>
and <SUBSECTION Standard>. The Standard subsection is for these
repetitive functions that appear all the time. The Private subsection is
for other functions that you don't want to document and should remain
hidden from the user, but you want to let gtk-doc know that it should
stop complaining about them.

The long and the short of it is that *-undocumented.txt and *-unused.txt
should be completely empty in a fully documented module.

> 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 :-)

Aaron Weber started to do a bit more of this last November. He improved
one of the documents we already had, although I think some more stuff
could be done: I don't think he got around to talking about
foo-sections.txt, foo-undocumented.txt and foo-unused.txt, for example.

Have a look at
http://mail.gnome.org/archives/gtk-doc-list/2003-November/thread.html --
in particular, the final two or three threads that month (where Aaron
and my names appear a lot). That might give you some ideas of what
remains to be done. Hopefully Aaron can let you know where he got to
with that stuff.

If that thread all seems too mysterious, let me know and I might write
down what is meant to be happening with the various build description
files. We didn't seem to explain things too clearly when Aaron was doing
his work, so I suspect somebody needs to take more time to be extremely
clear with what is happening during the build process. 

It is probably not a bad idea to also subscribe to the gtk-doc list,
since that is where most of the discussion about this tool takes place
(it is an *extremely* low-volume list, by and large).

[...]
> 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).

Agreed. The only consolation I can offer is that once you have it
working once, the next times are much easier. You already have all the
tools and most of the source code available. It is not just a matter of
doing periodic updates and rebuilding the new stuff.

Cheers,
Malcolm