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

[Owen Taylor <otaylor redhat com>]

Not Zed <notzed ximian com> writes:

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

Quite a bit:

 - If the format of the output is specified, what is it?
 - If the format of the output is not specified, say that
 - How do you convert back from a string?
 - What is the intended purpose of this function (is it a human
   readable string? A string for serialization?)

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

Well, the docs have 

 - a table of contents, organized topically
 - an object heirarchy
 - cross links out the wazoo

Is there anything else that should be added other than simply
having searching?

Regards,
                                        Owen