GNOME Bugzilla – Bug 761081
GSignal documentation improvements
Last modified: 2018-05-24 18:28:05 UTC
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.
> * 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. The documentation on how to use GSignal with return values should go in the tutorial, not the API reference. We already have two chapters for it: * https://developer.gnome.org/gobject/unstable/howto-signals.html * https://developer.gnome.org/gobject/unstable/signal.html > * 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. There is no requirement for variadic argument lists to be NULL terminated. We don't document negative requirements ("The list must not be..."); we document if the list has to be NULL (or any other sentinel) terminated.
Moving this to glib, where the signal documentation lives.
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/glib/issues/1127.