Re: API documentation, GtkTextBuffer signals

[Søren Wedel Nielsen <soren wedel nielsen gmail com>]

tir, 20 09 2005 kl. 09:12 -0400, skrev Matthias Clasen: 
> On Mon, 2005-09-19 at 23:39 +0200, S�Wedel Nielsen wrote:
> > Hi, 
> > 
> > I have written some documentation of the GtkTextBuffer signals. 
> > 
> > If this is useful I will try to find time to continue with more signals
> > - they seems to be neglected in most of the documentation.
> > 
> > I include a patch against 2.6.7 and would like to hear your
> > comments/criticism.
> 
> Looks good in general. 
> 
> I'm not sure that "There is no need to keep the iter valid in handlers
> which run after the default handler" is completely correct. What if
> there are multiple handlers after the default handler ?

Yes, then you would have to keep them valid. But would that not be less
surprising because you would have written the handlers yourself?
I see the whole "Note that if your handler..." as a warning that you can
interfere with the work of the gtk+ library itself (I got the
inspiration from the documentation of the delete-range signal).

I think it is a little too detailed to include "unless you add more than
one handler that depend on it" or something like that. And too unclear
to write "Normally there is no need to keep...".

Any ideas? Just remove the sentence? 

> While all the information about handlers that run before or after the 
> default handler is nice, it will not be too useful until gtk-doc
> actually documents the G_SIGNAL_RUN_... flags for each signal.

Even as it is now, it is nice to know that if you use g_signal_connect()
you has to be careful, and if you use g_signal_connect_after() you only
has to worry about your own code.

S�