+/**
+ * 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
+ * <emphasis>emission</emphasis> 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 i'm referring to those types as "object
+ * types" in the following, simply because that is the context most
+ * users will encounter signals in.
+ *
+ * ones and user provided ones.
+ * 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:
+ * <variablelist>
+ * <varlistentry><term></term><listitem><para>
+ * 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * 2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE)
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * 4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals
+ * </para></listitem></varlistentry>
+ * </variablelist>
+ * 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 <emphasis>blocked</emphasis>, 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.
+ */