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

[Liam Quin <liam holoweb net>]

On Wed, May 09, 2001 at 08:35:59AM -0400, Owen Taylor wrote:
> 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

Which is an interesting example of cryptic docs :-) e.g. there is no
description of what GTK_MESSAGE_QUESTION does, "Question requiring a choice"
is a very gnomic (sorry) explanation.

The ability to include screen shots here would take away a lot of
the mystery.  Is that a possibility?

I'd *really* like to see screen shots of every control / widget.  It's
difficult to describe a CTree or a Cauldron (!) in words, and a screen
shot makes it immediately clear.  Well. maybe not for a Cauldren, but
for the others :-)

I know that I, for one, tend to go to documentation, and use the source
only as a last resource -- if a function is not documented I would usually
rather write my own version that use it, because I assume that if it's
undocumented it is unsupported and might not work, or might go away on
the next release.  Part of that is years of using commercially supported
toolkits.  But I know that I am not alone in this.  A Windows C programmer
goes to the Visual C docs first, then to the MSDN network, not to
the source.


A couple of times I've made small bug reports about missing docs, and
developers went and improved the docs, which was good.

It's also really good to see the documentation improving.

Lee

-- 
Liam Quin - Barefoot in Toronto - liam holoweb net - http://www.holoweb.net/
Ankh: irc.sorcery.net www.valinor.sorcery.net irc.gnome.org www.advogato.org
Author, Open Source XML Database Toolkit, Wiley August 2000
Co-author: The XML Specification Guide, Wiley 1999; Mastering XML, Sybex 2001