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

[Sander Vesik <Sander Vesik Sun COM>]

On 10 May 2001, Not Zed wrote:

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

Unless it's O(1), how complex it is, if it uses floats anywhere, how
precice the result is (in ulp-s please), is it re-entrant/thread safe and
probably soe other things depending on what object toString() gets applied
to...

[snip]

>
>  !Z
> 

	Sander

One day a tortoise will learn to fly
	-- Terry Pratchett, 'Small Gods'