Re: gnome-vfs 1.0.1 is available

[Havoc Pennington <hp redhat com>]

Dropping gnome-announce from the CC list - the moderators are
probably getting tired of bouncing this thread. ;-)

Joel Becker <jlbec evilplan org> writes: 
> 	Do you have a pointer to the output somewheres for a quick look?
> One of the things I've noticed about gtkdoc generated stuff is that 90%
> of it is just prototype reiteration.  No documentation of what things
> actually do.  OTOH, Sun's javadoc for the standard API is pretty much
> 'learn from the reference'.  Some of that is surely the OO-nature of
> Java, but other of it is the fact that 'parsing the prototypes' !=
> 'actual documentation'
> 

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.

It's just a matter of doing the work to write nice docs. Nothing about
gtk-doc prevents that. The doc comments can be long, multi-paragraph,
and explain as much as you want. And the .tmpl files can contain long
overview sections with examples.

The best way to avoid writing docs is to go on the "let's program some
docs tools intead of writing docs" tangent. ;-)

Havoc