API docs [ was Re: gnome-vfs 1.0.1 is available ]

[Owen Taylor <otaylor redhat com>]

Joel Becker <jlbec evilplan org> writes:

> > I don't think we can blame the tools for this. Javadoc and gtk-doc
> > are essentially equivalent in what kinds of docs you can write.
> > 
> > The best way to avoid writing docs is to go on the "let's program some
> > docs tools intead of writing docs" tangent. ;-)
> 
> 	I think I wasn't clear.  I wasn't intending to say "let's
> program doc tools."  I was saying "Can I see what the output was,
> because running gtkdoc against things != documented."  

There is quite a bit of documented stuff you can look at; most
of GLib, or to pick a random GTK+ example:

 http://developer.gnome.org/doc/API/2.0/gtk/gtkmessagedialog.html

(Need to get Dave's modification to the gtk-doc .dsl back in place, so
that we have red bars, not red-green-blue bars....)

> I've spent the
> last week back in the Java world, and the API docs are spectacular
> (though a few spots aren't as clear as I'd like, they do well for the
> scope of the API).

Personally, I think we can do a _lot_ better than the Java docs. The
member function docs often are just reiteration of the name, and the
class documentation is quite frequently insufficient. There are good
topic overview docs, but they are not integrated with the API docs at
all.

> The GTK+ docs are ugly to start with, hard to navigate beyond that,

Do you have specific suggestions?

 and when you do find the function you want, 20% of the time there
> is nothing beyond the prototype and maybe a blurb for each argument.
> This is not to disparage the effort that has gone into the documentation
> so far.  What we have is worlds better than it was two years ago (where
> I would say that 90% of things were merely the prototype).  The
> work on 2.0 documentation is especially encouraging.  However, while
> GTK+/GLib have come a long way, much of the GNOME API space has not.
> Hence we have situations like the gnome-vfs one.
>
> 	I keep coming back to the fact that I cannot understand gtk/glib/gnome
> from the docs.  I have the source on *every* machine I use so I can find
> out what a function actually does.  This is fine for us UTSL hackers, but
> really isn't the Right Thing for a mature API.

Well, I think the problem here is that much of the GNOME community
does go first to the source, so the docs don't get much stress
testing.

Here's a suggestion, keep a browser open on developer.gnome.org/doc/API,
and the next time you are tempted to go to the source to find
something out, go to the reference docs instead, and if you
don't find the information you needed, make a bug report in 
bugzilla against the docs component of the library.

[ N.B. - the GTK+-2.0 docs are a fair bit more complete than the
         GTK+-1.2 docs, so doing this for GNOME-1.4 programming
         may result in a lot of bug reports getting closed as
         already-fixed. That's OK. ]

Regards,
                                        Owen