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

[Joel Becker <jlbec evilplan org>]

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:

	Yeah, my origninal request was regarding the initial run of
gtkdoc on gnome-vfs.  I'm aare of glib/gtk+'s status.

> 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 class overview docs are usually quite usable IMRecentE,
especially Swing.  However, your comment on the integration of overvew
stuff is spot on.  They often link the Java Tutorial, which is *not*
part of the downloadable bundle, so if you are offline you are SOL.

> > The GTK+ docs are ugly to start with, hard to navigate beyond that,
> 
> Do you have specific suggestions?

	Well, I don't know how people would react to frames, nor do I
know if DocBook/Jade can generate them, but I find the frameset around
the Java API really useful.  It's a bit more painful to go back and
forth between classes in our docs.  To move from javax.swing.JEditorPane
to java.util.StringTokenizer is three browser clicks (scroll the package
frame, click on java.util, click on StringTokenizer in the Class frame),
and this is all onscreen.  gtkdoc requires back and forth browsing,
which breaks up the continuity some.  (also, sometimes gnome.org is
quite slow, making traversal extra painful, but that isn't gtkdoc's
fault).
	I just don't quite go with the pink + red + black + whatever
look our current style set has.  It's, um, jarring.  The tables could be
bordered nicely too.  It's not that 'prettiness' is all that a doc set
should have, but it makes it more readable and scanable visually.

> 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.

	Ok, I can do that I guess.  I'd be more inclined to add a doc,
if the inline vs tmpl wasn't so confusing :-)

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

	I noted that in my previous email.  I was quite impressed as
to their completeness.  I did not mean to single out glib/gtk+, as they
seem to be the class of the field.

Joel

-- 

"Sometimes I think the surest sign intelligent
 life exists elsewhere in the universe is that
 none of it has tried to contact us."
                                -Calvin & Hobbes

			http://www.jlbec.org/
			jlbec evilplan org