Re: gtk-doc manuals

[Malcolm Tredinnick <malcolm commsecure com au>]

Hey Aaron.

I think it's great that you have to time to organise this. Comprehensive
documentation for gtk-doc is something that is sorely needed. A few
comments below, based on my experiences helping other people...

On Tue, 2003-11-18 at 06:13, Aaron Weber wrote:
> David:
>   I may need quite a bit of help-- I'm not much of a programmer, so I
> don't know the best ways to go about documenting APIs directly.
> 
> I've got reasonably good information on how the gtk-doc system itself
> works now... not quite what I thought it was the first time:

Heh. Everybody goes through that phase. :-)

> 
> 1) You paste some special code into your makefiles.
> 2) At make/make install gtk-doc does its thing; you never run it
> actively.
> 3) gtk-doc Extracts specially-designated comments from .h files and
> creates SGML templates and section-listing/organizational files

It also extracts them from *.c files and files in the tmpl/ directory.

> 4) Edit those files by hand
> 5) gtk-doc does its thing next time you make/make install. 
> 
> There are several things that developers need to have spelled out for
> them, some of which are already available, and some of which are not: 
> 
> * What code exactly gets pasted into which Makefiles?
> * What comments need to be added to .h files, and how should they be
> formatted?
> * What happens when you make install after editing the template files?

I don't quite understand what you are saying here, but I assume it makes
sense to you, so I'll let it slide. Something I would like to see
mentioned is some instructions on how to force the documentation
regeneration. More than once I have helped people with problems where
they have changed the docstrings in the code and it hasn't made it into
the documentation (because the code was no rescanned). The solution in
those cases is to remove *.stamp in the directory where gtk-doc is
called, which forces a complete rebuild.

> * Where do the finished docs show up for other developers to read them?
> * How do you contribute to developer docs if you didn't write the
> original software?
> * What's the best way to document particular sorts of objects or
> functions?

I would also add to this list:

- how to originally set up the master file (the XML file that includes
all the files generated from the templates). In fact, just generally how
to start things off.

- how to maintain the *-sections.txt file. In particular, possible ways
to order that file, what the special tags are for, etc.

- how to ensure that newly added functions are included in the
documentation (they need to be manually added to *-sections.txt).

- What happens when there are comments both in the source and the
corresponding file in tmpl/ for the same code (the source comment wins).

- Be careful when the declaration in the header file for a function does
not match the definition in the C file for that function. gtk-doc gets
confused (although it does spit out errors, so you know something is
wrong).

- Why is it standard practice to ship with --enable-gtk-doc set to "no"
in tarballs (because too many people do not have a good docs build setup
and it is painful to have debug the same thing four thousand times). How
to ensure that the docs build is enabled when running 'make distcheck'
(for automake >= 1.6 this is pretty easy, for older automakes it is more
fiddly).

> Also we need to provide the .emacs elisp function that automatically
> inserts that comment structure (this is floating around; I think JPR has
> a copy of it)

Zucchi's original version is in gtk-doc/tools. Of course, JPR may have
fixed bugs, amended it to also play space invaders, or done whatever
else emacs users are prone to do.

> The way I see it there are a couple of types of people who will be
> reading this information: either the actual project hackers, or more
> peripheral people who want to add to developer docs but aren't actually
> contributing a lot to the code itself. The first group probably doesn't
> need as much hand-holding as the other, but they'll both want to have a
> lot of information available, and probably some good, well-commented
> examples.

My experience with helping a lot of people with gtk-doc over the past
couple of years has been that the developers are just as confused as
anybody. And the general feeling is that they do not want to spend a lot
of time getting things right. So anything you can write that ends up
being a step-by-step guide to having stuff Just Work should be
appreciated by a lot of new developers.

> As I mentioned earlier, a lot of this is already available in one or
> another place, so significant portions of the task will be organizing,
> sorting, updating, and so forth: we want to make sure that it's all in
> one place, and easy to maintain, so that when it changes, we don't have
> an out-of-date version posted somewhere... 

Note that the original attempt at a manual (in gtk-doc/help/manual/C) is
mostly correct in the first few sections, but then dissolves into a
discussion of old DocBook DTDs and DSSSL templates and the like. It is
important these days that API documentation uses XML mode when running
gtk-doc: partially for accessibility reasons -- the generated HTML is
better -- and partially for maintainability reasons -- the stylesheets
are more maintained. The sgml mode is really just for backwards
compatibility.

> Gtk+, fortunately, provides lots of great examples, so we're mostly set
> there.
> 
> I do think we should have a man page, even if it just says "gtk-doc is
> not run at the command line. This manual page is not used. See the file
> doc/setting-up.txt or the page
> developer.gnome.org/gtk-doc/instructions.php"

It is a little hard to tell from your email if any of your points were
things you still needed to find out, but I am assuming you were just
laying out the plan of attack.

Looks good, in any case. Best of luck.

Cheers,
Malcolm