Re: gnome-vfs 1.0.1 is available

[Joel Becker <jlbec evilplan org>]

On Wed, May 09, 2001 at 12:51:29AM -0400, Havoc Pennington wrote:
> 
> Dropping gnome-announce from the CC list - the moderators are
> probably getting tired of bouncing this thread. ;-)

	Yeah, sorry about that.  I didn't realize it until I got the
moderation bounce.

> 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."  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).
	The GTK+ docs are ugly to start with, hard to navigate beyond
that, 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.
	What can be done?  I shouldn't, of course, bitch and moan while
doing nothing myself.  So I'm going to make an effort.  If I have to
look up a function, I'll try to document what I didn't know.  That won't
solve navigation or 'prettiness', but I'll be doing my part.
	Certainly we get nowhere bitching about the current release's
docs.  We just need to work on them.


Joel

-- 

The zen have a saying:
"When you learn how to listen, ANYONE can be your teacher."

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