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

[Not Zed <notzed ximian com>]

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

Well with the wonderfully long and excruciatingly concise function names
(for trivial methods) that java programmers like to use, repeating the
method name is all you *can* do to document a function, without just
sounding stupid.  gtk+ and gnome functions often follow a similar trend.

e.g.

 toString()
   Converts to a string.

I mean, what else can you say?

(I knew some guy who made a Utils.removeLeadingAndTrailingSpaces()
method.  That always cracked me up!!!)


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

Last time i looked, it was like trying to read a manual that had been
printed on fanfold paper, with no indexing or page numbers, and no
inter-page layout; its just painful, you have to do a lot of manual (no
pun intended!) searching.  Yes i'm overexagerating, but thats the
general impression I got when I tried to use it.  I gave up and stuck to
the source.

 !Z