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)