i've heard it reported to me a couple of times now that the incomplete documentation of things as fundamental as signals on GtkWidget is a bit of an embarrassment.

many of our signals, for example, have no docs at all beyond the parameters:

widget : the object which received the signal.
user_data : user data set when the signal handler was connected.

which is pretty useless.

we need to go through and fill these in better.  ideally, a description of what it means and under what circumstances it is fired.  at the very least, if we don't expect people to understand what its purpose is we should have a note to the effect of "this is an internal signal not intended to be used from outside of gtk".