Re: [gtk-list] DOCUMENTATION (yes, this is shouted)

[Elliot Lee <sopwith redhat com>]

On Fri, 21 Aug 1998, Juergen A. Erhard wrote:

> Now, am I the only programmer who sometimes puts some comments in his
> code?  The gtkprogress.c, for example, sports exactly 5(!) comments. 
> And this is counting the copyright header and one comment that consists
> of a row of '*'. How should *anyone* understand what's going on?

By reading the C code. If you're not able to understand C, then no amount
of comments will do you good ;-)

Good comments say -why- something is done, and it sounds at this point as
if you're having trouble understanding -what- is being done.

> Face it: the documentation situation is *the* major problem GTK has... 
> (especially compared to QT).  No, the tutorial doesn't cut it... 
> *reference docs* are what an experienced developer needs in the long
> run. I can't go through the tutorial every time I need the semantics of
> a certain function...

The semantics of functions are fairly obvious by reading the header files. 
Reading the source code itself might confuse you if you are just wanting
to use the API and not the internals. 

What specifically are you trying to do?

I'm not arguing against documentation! (I try to comment my functions, but
that is only to balance against its occasional ugliness ;-)  I just think
that what you specifically want to do can be done easily by reading the
header files.
-- Elliot
Progress (n.): The process through which Usenet has evolved from smart
people in front of dumb terminals to dumb people in front of smart
terminals.  -- obs@burnout.demon.co.uk