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

[Havoc Pennington <rhpennin midway uchicago edu>]

On Fri, 21 Aug 1998, Elliot Lee wrote:
> 
> 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.
>

Hrm, not really.

Take:
gchar*     gtk_editable_get_chars      (GtkEditable      *editable,
					gint              start_pos,
					gint              end_pos);

which has no comment. Do I free the return value or not? have to look in
gtkeditable.c, which I've in fact done more than once 'cuz I always
forget. In fact I can't tell you now, though I've used this function more
than once.

Or this one led me to read the entire .c file:

GtkObject* gtk_adjustment_new		(gfloat		  value,
					 gfloat		  lower,
				         gfloat		  upper,
				         gfloat           step_increment,
				         gfloat           page_increment,
				         gfloat           page_size);

What the hell do the last three args do, using only what you know from the
header file? I don't think it's very obvious.

So those are some "what" issues it would be nice to have comments for. The
code does indeed tell you what is happening, but the headers don't, only
the full-scale source. And when it's a "holistic" question like the
meaning of page_increment, you have to read a lot of source, not just the
function in question (since it just sets a struct member). It is not
impossible to find the answers, and I do, but it's kind gratuitously
labor-intensive.

The "why" isn't there either, though. I've spent a lot of time reading
source to figure out how GtkArg works this morning, but why it's that way
mostly escapes me still. And widget source is almost impossible to
understand until you figure out the request/allocate business for
geometry, but figuring that out when you don't know how to use Gtk is
difficult, because you have to have a holistic view of Gtk geometry
management for it to make much sense. Which means reading a whole lot of
source.

The situation is made much better because there are lots of good examples
and the tutorial available, but you have to use those, not the headers.
grep is your friend.

Anyway, I think it's a valid concern, and it would be a useful project to
go through and add comments, IMO. 

Havoc