Re: API docs [ was Re: gnome-vfs 1.0.1 is available ]
- From: Owen Taylor <otaylor redhat com>
- To: Not Zed <notzed ximian com>
- Cc: gnome-hackers gnome org
- Subject: Re: API docs [ was Re: gnome-vfs 1.0.1 is available ]
- Date: 09 May 2001 21:27:25 -0400
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.
> 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
gnome-hackers mailing list
gnome-hackers gnome org
] [Thread Prev