From a60e6bedaede5cf0cf6e2e0ed5f4ad824a7446c3 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 6 Mar 2024 13:25:38 +0000 Subject: [PATCH] docs: Document that signal connection functions cannot fail MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The documentation previously implied that they could. That’s not really true though: they can only fail if preconditions fail, i.e. they’re passed invalid input. That’s a programmer error, which is not something we want to encourage people to check for at runtime (e.g. by dynamically checking for a 0 return value). Signed-off-by: Philip Withnall --- gobject/gsignal.c | 15 ++++++++++++--- gobject/gsignal.h | 15 ++++++++++++--- 2 files changed, 24 insertions(+), 6 deletions(-) diff --git a/gobject/gsignal.c b/gobject/gsignal.c index 755a515d8..a5b471cb3 100644 --- a/gobject/gsignal.c +++ b/gobject/gsignal.c @@ -2301,7 +2301,10 @@ g_signal_get_invocation_hint (gpointer instance) * If @closure is a floating reference (see g_closure_sink()), this function * takes ownership of @closure. * - * Returns: the handler ID (always greater than 0 for successful connections) + * This function cannot fail. If the given signal doesn’t exist, a critical + * warning is emitted. + * + * Returns: the handler ID (always greater than 0) */ gulong g_signal_connect_closure_by_id (gpointer instance, @@ -2366,7 +2369,10 @@ g_signal_connect_closure_by_id (gpointer instance, * If @closure is a floating reference (see g_closure_sink()), this function * takes ownership of @closure. * - * Returns: the handler ID (always greater than 0 for successful connections) + * This function cannot fail. If the given signal doesn’t exist, a critical + * warning is emitted. + * + * Returns: the handler ID (always greater than 0) */ gulong g_signal_connect_closure (gpointer instance, @@ -2462,7 +2468,10 @@ node_check_deprecated (const SignalNode *node) * used. Specify @connect_flags if you need `..._after()` or * `..._swapped()` variants of this function. * - * Returns: the handler ID (always greater than 0 for successful connections) + * This function cannot fail. If the given signal doesn’t exist, a critical + * warning is emitted. + * + * Returns: the handler ID (always greater than 0) */ gulong g_signal_connect_data (gpointer instance, diff --git a/gobject/gsignal.h b/gobject/gsignal.h index 5bcbb0d4d..52d08a809 100644 --- a/gobject/gsignal.h +++ b/gobject/gsignal.h @@ -508,7 +508,10 @@ void g_signal_chain_from_overridden_handler (gpointer instance, * See [memory management of signal handlers](signals.html#Memory_management_of_signal_handlers) for * details on how to handle the return value and memory management of @data. * - * Returns: the handler ID, of type #gulong (always greater than 0 for successful connections) + * This function cannot fail. If the given signal doesn’t exist, a critical + * warning is emitted. + * + * Returns: the handler ID, of type `gulong` (always greater than 0) */ /* Intentionally not using G_CONNECT_DEFAULT here to avoid deprecation * warnings with older GLIB_VERSION_MAX_ALLOWED */ @@ -525,7 +528,10 @@ void g_signal_chain_from_overridden_handler (gpointer instance, * * The handler will be called synchronously, after the default handler of the signal. * - * Returns: the handler ID, of type #gulong (always greater than 0 for successful connections) + * This function cannot fail. If the given signal doesn’t exist, a critical + * warning is emitted. + * + * Returns: the handler ID, of type `gulong` (always greater than 0) */ #define g_signal_connect_after(instance, detailed_signal, c_handler, data) \ g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_AFTER) @@ -563,7 +569,10 @@ void g_signal_chain_from_overridden_handler (gpointer instance, * (GCallback) button_clicked_cb, other_widget); * ]| * - * Returns: the handler ID, of type #gulong (always greater than 0 for successful connections) + * This function cannot fail. If the given signal doesn’t exist, a critical + * warning is emitted. + * + * Returns: the handler ID, of type `gulong` (always greater than 0) */ #define g_signal_connect_swapped(instance, detailed_signal, c_handler, data) \ g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_SWAPPED)