Merge branch 'fix-signal-connect-docs' into 'main'

gsignal: Add clarification on 'detailed_signal' validation

Closes #3540

See merge request GNOME/glib!4416

gobject/gobject.c

@@ -5155,6 +5155,14 @@ g_value_dup_object (const GValue *value)
  * emitting a signal while @gobject is being destroyed in another thread
  * is not safe).
  *
+ * This function cannot fail. If the given signal name doesn’t exist,
+ * a critical warning is emitted. No validation is performed on the
+ * "detail" string when specified in @detailed_signal, other than a
+ * non-empty check.
+ *
+ * Refer to the [signals documentation](signals.html) for more
+ * details.
+ *
  * Returns: the handler id.
  */
 gulong

gobject/gsignal.c

@@ -2300,8 +2300,13 @@ g_signal_get_invocation_hint (gpointer instance)
  * If @closure is a floating reference (see g_closure_sink()), this function
  * takes ownership of @closure.
  *
- * This function cannot fail. If the given signal doesn’t exist, a critical
+ * This function cannot fail. If the given signal name doesn’t exist,
- * warning is emitted.
+ * a critical warning is emitted. No validation is performed on the
+ * ‘detail’ string when specified in @detailed_signal, other than a
+ * non-empty check.
+ *
+ * Refer to the [signals documentation](signals.html) for more
+ * details.
  *
  * Returns: the handler ID (always greater than 0)
  */
@@ -2368,8 +2373,13 @@ g_signal_connect_closure_by_id (gpointer  instance,
  * If @closure is a floating reference (see g_closure_sink()), this function
  * takes ownership of @closure.
  *
- * This function cannot fail. If the given signal doesn’t exist, a critical
+ * This function cannot fail. If the given signal name doesn’t exist,
- * warning is emitted.
+ * a critical warning is emitted. No validation is performed on the
+ * ‘detail’ string when specified in @detailed_signal, other than a
+ * non-empty check.
+ *
+ * Refer to the [signals documentation](signals.html) for more
+ * details.
  *
  * Returns: the handler ID (always greater than 0)
  */
@@ -2467,8 +2477,13 @@ node_check_deprecated (const SignalNode *node)
  * used. Specify @connect_flags if you need `..._after()` or
  * `..._swapped()` variants of this function.
  *
- * This function cannot fail. If the given signal doesn’t exist, a critical
+ * This function cannot fail. If the given signal name doesn’t exist,
- * warning is emitted.
+ * a critical warning is emitted. No validation is performed on the
+ * ‘detail’ string when specified in @detailed_signal, other than a
+ * non-empty check.
+ *
+ * Refer to the [signals documentation](signals.html) for more
+ * details.
  *
  * Returns: the handler ID (always greater than 0)
  */

gobject/gsignal.h

@@ -508,8 +508,13 @@ 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.
  * 
- * This function cannot fail. If the given signal doesn’t exist, a critical
+ * This function cannot fail. If the given signal name doesn’t exist,
- * warning is emitted.
+ * a critical warning is emitted. No validation is performed on the
+ * ‘detail’ string when specified in @detailed_signal, other than a
+ * non-empty check.
+ *
+ * Refer to the [signals documentation](signals.html) for more
+ * details.
  *
  * Returns: the handler ID, of type `gulong` (always greater than 0)
  */
@@ -528,8 +533,13 @@ void   g_signal_chain_from_overridden_handler (gpointer           instance,
  * 
  * The handler will be called synchronously, after the default handler of the signal.
  * 
- * This function cannot fail. If the given signal doesn’t exist, a critical
+ * This function cannot fail. If the given signal name doesn’t exist,
- * warning is emitted.
+ * a critical warning is emitted. No validation is performed on the
+ * ‘detail’ string when specified in @detailed_signal, other than a
+ * non-empty check.
+ *
+ * Refer to the [signals documentation](signals.html) for more
+ * details.
  *
  * Returns: the handler ID, of type `gulong` (always greater than 0)
  */
@@ -569,8 +579,13 @@ void   g_signal_chain_from_overridden_handler (gpointer           instance,
  *                   (GCallback) button_clicked_cb, other_widget);
  * ]|
  * 
- * This function cannot fail. If the given signal doesn’t exist, a critical
+ * This function cannot fail. If the given signal name doesn’t exist,
- * warning is emitted.
+ * a critical warning is emitted. No validation is performed on the
+ * ‘detail’ string when specified in @detailed_signal, other than a
+ * non-empty check.
+ *
+ * Refer to the [signals documentation](signals.html) for more
+ * details.
  *
  * Returns: the handler ID, of type `gulong` (always greater than 0)
  */