docs: Move the signal SECTION

Move the content to the new signals.md file.

Helps: #3037

docs/reference/gobject/gobject.toml.in

@@ -45,6 +45,7 @@ content_files = [
   "concepts.md",
   "tutorial.md",
   "types.md",
+  "signals.md",
   "floating-refs.md",
   "boxed.md",
   "enum-types.md",

docs/reference/gobject/meson.build

@@ -73,6 +73,7 @@ expand_content_files = [
   'gvalue.md',
   'tutorial.md',
   'types.md',
+  'signals.md',
 ]
 
 gobject_gir = meson.current_source_dir() / 'GObject-2.0.gir'

docs/reference/gobject/signals.md

@@ -0,0 +1,95 @@
+Title: Signals
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2000, 2001 Tim Janik
+SPDX-FileCopyrightText: 2000 Owen Taylor
+SPDX-FileCopyrightText: 2002, 2014 Matthias Clasen
+SPDX-FileCopyrightText: 2014 Collabora, Ltd.
+SPDX-FileCopyrightText: 2019 Endless Mobile, Inc.
+
+# Signals
+
+The basic concept of the signal system is that of the emission
+of a signal. Signals are introduced per-type and are identified
+through strings. Signals introduced for a parent type are available
+in derived types as well, so basically they are a per-type facility
+that is inherited.
+
+A signal emission mainly involves invocation of a certain set of
+callbacks in precisely defined manner. There are two main categories
+of such callbacks, per-object ones and user provided ones.
+(Although signals can deal with any kind of instantiatable type, I'm
+referring to those types as "object types" in the following, simply
+because that is the context most users will encounter signals in.)
+The per-object callbacks are most often referred to as "object method
+handler" or "default (signal) handler", while user provided callbacks are
+usually just called "signal handler".
+
+The object method handler is provided at signal creation time (this most
+frequently happens at the end of an object class' creation), while user
+provided handlers are frequently connected and disconnected to/from a
+certain signal on certain object instances.
+
+A signal emission consists of five stages, unless prematurely stopped:
+
+1. Invocation of the object method handler for `G_SIGNAL_RUN_FIRST` signals
+
+2. Invocation of normal user-provided signal handlers (where the @after
+   flag is not set)
+
+3. Invocation of the object method handler for `G_SIGNAL_RUN_LAST` signals
+
+4. Invocation of user provided signal handlers (where the @after flag is set)
+
+5. Invocation of the object method handler for `G_SIGNAL_RUN_CLEANUP` signals
+
+The user-provided signal handlers are called in the order they were
+connected in.
+
+All handlers may prematurely stop a signal emission, and any number of
+handlers may be connected, disconnected, blocked or unblocked during
+a signal emission.
+
+There are certain criteria for skipping user handlers in stages 2 and 4
+of a signal emission.
+
+First, user handlers may be blocked. Blocked handlers are omitted during
+callback invocation, to return from the blocked state, a handler has to
+get unblocked exactly the same amount of times it has been blocked before.
+
+Second, upon emission of a `G_SIGNAL_DETAILED` signal, an additional
+`detail` argument passed in to [func@GObject.signal_emit] has to match
+the detail argument of the signal handler currently subject to invocation.
+Specification of no detail argument for signal handlers (omission of the
+detail part of the signal specification upon connection) serves as a
+wildcard and matches any detail argument passed in to emission.
+
+While the `detail` argument is typically used to pass an object property name
+(as with `GObject::notify`), no specific format is mandated for the detail
+string, other than that it must be non-empty.
+
+## Memory management of signal handlers
+
+If you are connecting handlers to signals and using a `GObject` instance as
+your signal handler user data, you should remember to pair calls to
+[func@GObject.signal_connect] with calls to [func@GObject.signal_handler_disconnect]
+or [func@GObject.signal_handlers_disconnect_by_func]. While signal handlers are
+automatically disconnected when the object emitting the signal is finalised,
+they are not automatically disconnected when the signal handler user data is
+destroyed. If this user data is a `GObject` instance, using it from a
+signal handler after it has been finalised is an error.
+
+There are two strategies for managing such user data. The first is to
+disconnect the signal handler (using [func@GObject.signal_handler_disconnect]
+or [func@GObject.signal_handlers_disconnect_by_func]) when the user data (object)
+is finalised; this has to be implemented manually. For non-threaded programs,
+[func@GObject.signal_connect_object] can be used to implement this automatically.
+Currently, however, it is unsafe to use in threaded programs.
+
+The second is to hold a strong reference on the user data until after the
+signal is disconnected for other reasons. This can be implemented
+automatically using [func@GObject.signal_connect_data].
+
+The first approach is recommended, as the second approach can result in
+effective memory leaks of the user data if the signal handler is never
+disconnected for some reason.
+

gobject/gsignal.c

@@ -39,99 +39,6 @@
 #include "gobject_trace.h"
 
 
-/**
- * SECTION:signals
- * @short_description: A means for customization of object behaviour
- *     and a general purpose notification mechanism
- * @title: Signals
- *
- * The basic concept of the signal system is that of the emission
- * of a signal. Signals are introduced per-type and are identified
- * through strings. Signals introduced for a parent type are available
- * in derived types as well, so basically they are a per-type facility
- * that is inherited.
- *
- * A signal emission mainly involves invocation of a certain set of
- * callbacks in precisely defined manner. There are two main categories
- * of such callbacks, per-object ones and user provided ones.
- * (Although signals can deal with any kind of instantiatable type, I'm
- * referring to those types as "object types" in the following, simply
- * because that is the context most users will encounter signals in.)
- * The per-object callbacks are most often referred to as "object method
- * handler" or "default (signal) handler", while user provided callbacks are
- * usually just called "signal handler".
- *
- * The object method handler is provided at signal creation time (this most
- * frequently happens at the end of an object class' creation), while user
- * provided handlers are frequently connected and disconnected to/from a
- * certain signal on certain object instances.
- *
- * A signal emission consists of five stages, unless prematurely stopped:
- *
- * 1. Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals
- *
- * 2. Invocation of normal user-provided signal handlers (where the @after
- *    flag is not set)
- *
- * 3. Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals
- *
- * 4. Invocation of user provided signal handlers (where the @after flag is set)
- *
- * 5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals
- *
- * The user-provided signal handlers are called in the order they were
- * connected in.
- *
- * All handlers may prematurely stop a signal emission, and any number of
- * handlers may be connected, disconnected, blocked or unblocked during
- * a signal emission.
- *
- * There are certain criteria for skipping user handlers in stages 2 and 4
- * of a signal emission.
- *
- * First, user handlers may be blocked. Blocked handlers are omitted during
- * callback invocation, to return from the blocked state, a handler has to
- * get unblocked exactly the same amount of times it has been blocked before.
- *
- * Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional
- * @detail argument passed in to g_signal_emit() has to match the detail
- * argument of the signal handler currently subject to invocation.
- * Specification of no detail argument for signal handlers (omission of the
- * detail part of the signal specification upon connection) serves as a
- * wildcard and matches any detail argument passed in to emission.
- *
- * While the @detail argument is typically used to pass an object property name
- * (as with #GObject::notify), no specific format is mandated for the detail
- * string, other than that it must be non-empty.
- *
- * ## Memory management of signal handlers # {#signal-memory-management}
- *
- * If you are connecting handlers to signals and using a #GObject instance as
- * your signal handler user data, you should remember to pair calls to
- * g_signal_connect() with calls to g_signal_handler_disconnect() or
- * g_signal_handlers_disconnect_by_func(). While signal handlers are
- * automatically disconnected when the object emitting the signal is finalised,
- * they are not automatically disconnected when the signal handler user data is
- * destroyed. If this user data is a #GObject instance, using it from a
- * signal handler after it has been finalised is an error.
- *
- * There are two strategies for managing such user data. The first is to
- * disconnect the signal handler (using g_signal_handler_disconnect() or
- * g_signal_handlers_disconnect_by_func()) when the user data (object) is
- * finalised; this has to be implemented manually. For non-threaded programs,
- * g_signal_connect_object() can be used to implement this automatically.
- * Currently, however, it is unsafe to use in threaded programs.
- *
- * The second is to hold a strong reference on the user data until after the
- * signal is disconnected for other reasons. This can be implemented
- * automatically using g_signal_connect_data().
- *
- * The first approach is recommended, as the second approach can result in
- * effective memory leaks of the user data if the signal handler is never
- * disconnected for some reason.
- */
-
-
 #define REPORT_BUG      "please report occurrence circumstances to https://gitlab.gnome.org/GNOME/glib/issues/new"
 
 /* --- typedefs --- */