GSignal documentation improvements
Submitted by Sebastian
Link to original bug (#761081)
Description
I would like to suggest the following improvements for the GSignal module:
-
In the 'Description' section, give a general overview of how return values of signals work and maybe also a small code example. In particular this should mention that the return value of the user_function is the return value that g_signal_emit receives. Explain that when multiple signal handlers are connected to a signal, then accumulates are used to decide how signal propagation stops and which value is returned. Also explain that when a return value is specified on signal creation, then an accumulator must be specified as well.
-
In g_signal_new, for parameter 'return_type' clarify that specifying a return type implies that an accumulator is given as well.
-
In g_signal_new, for parameter 'accumulator', clarify that "maybe be NULL" only applies if no return type is specified. Also make it easier to discover the default functions: g_signal_accumulator_true_handled and g_signal_accumulator_first_wins by referencing them here.
-
In g_signal_emit* maybe mention that the ... parameter list does not need to be NULL terminated. I am not sure whats the standard convention here, I am under the impression that variadic lists are usually NULL terminated in glib, if thats not the case, then just leave it as it is.