<!-- ##### FUNCTION g_param_spec_boolean ##### -->
<para>
+Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN
+property.
+</para>
+<para>
+See g_param_spec_internal() for details on property names.
</para>
-@name:
-@nick:
-@blurb:
-@default_value:
-@flags:
-@Returns:
+@name: canonical name of the property specified
+@nick: nick name for the property specified
+@blurb: description of the property specified
+@default_value: default value for the property specified
+@flags: flags for the property specified
+@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_boolean ##### -->
<!-- ##### FUNCTION g_param_spec_char ##### -->
<para>
+Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property.
</para>
-@name:
-@nick:
-@blurb:
-@minimum:
-@maximum:
-@default_value:
-@flags:
-@Returns:
+@name: canonical name of the property specified
+@nick: nick name for the property specified
+@blurb: description of the property specified
+@minimum: minimum value for the property specified
+@maximum: maximum value for the property specified
+@default_value: default value for the property specified
+@flags: flags for the property specified
+@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_char ##### -->
<!-- ##### FUNCTION g_param_spec_uchar ##### -->
<para>
+Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property.
</para>
-@name:
-@nick:
-@blurb:
-@minimum:
-@maximum:
-@default_value:
-@flags:
-@Returns:
+@name: canonical name of the property specified
+@nick: nick name for the property specified
+@blurb: description of the property specified
+@minimum: minimum value for the property specified
+@maximum: maximum value for the property specified
+@default_value: default value for the property specified
+@flags: flags for the property specified
+@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_uchar ##### -->
<!-- ##### FUNCTION g_param_spec_int ##### -->
<para>
+Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property.
+</para>
+<para>
+See g_param_spec_internal() for details on property names.
</para>
-@name:
-@nick:
-@blurb:
-@minimum:
-@maximum:
-@default_value:
-@flags:
-@Returns:
+@name: canonical name of the property specified
+@nick: nick name for the property specified
+@blurb: description of the property specified
+@minimum: minimum value for the property specified
+@maximum: maximum value for the property specified
+@default_value: default value for the property specified
+@flags: flags for the property specified
+@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_int ##### -->
<!-- ##### FUNCTION g_param_spec_uint ##### -->
<para>
+Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property.
+</para>
+<para>
+See g_param_spec_internal() for details on property names.
</para>
-@name:
-@nick:
-@blurb:
-@minimum:
-@maximum:
-@default_value:
-@flags:
-@Returns:
+@name: canonical name of the property specified
+@nick: nick name for the property specified
+@blurb: description of the property specified
+@minimum: minimum value for the property specified
+@maximum: maximum value for the property specified
+@default_value: default value for the property specified
+@flags: flags for the property specified
+@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_uint ##### -->
<!-- ##### FUNCTION g_param_spec_long ##### -->
<para>
+Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property.
+</para>
+<para>
+See g_param_spec_internal() for details on property names.
</para>
-@name:
-@nick:
-@blurb:
-@minimum:
-@maximum:
-@default_value:
-@flags:
-@Returns:
+@name: canonical name of the property specified
+@nick: nick name for the property specified
+@blurb: description of the property specified
+@minimum: minimum value for the property specified
+@maximum: maximum value for the property specified
+@default_value: default value for the property specified
+@flags: flags for the property specified
+@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_long ##### -->
<!-- ##### FUNCTION g_param_spec_ulong ##### -->
<para>
-Create a new #GParamSpecULong instance specifying a %G_TYPE_ULONG property.
+Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG property.
+</para>
+<para>
+See g_param_spec_internal() for details on property names.
</para>
-@name:
-@nick:
-@blurb:
-@minimum:
-@maximum:
-@default_value:
-@flags:
-@Returns:
+@name: canonical name of the property specified
+@nick: nick name for the property specified
+@blurb: description of the property specified
+@minimum: minimum value for the property specified
+@maximum: maximum value for the property specified
+@default_value: default value for the property specified
+@flags: flags for the property specified
+@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_ulong ##### -->
<!-- ##### FUNCTION g_param_spec_int64 ##### -->
<para>
+Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property.
+</para>
+<para>
+See g_param_spec_internal() for details on property names.
</para>
-@name:
-@nick:
-@blurb:
-@minimum:
-@maximum:
-@default_value:
-@flags:
-@Returns:
+@name: canonical name of the property specified
+@nick: nick name for the property specified
+@blurb: description of the property specified
+@minimum: minimum value for the property specified
+@maximum: maximum value for the property specified
+@default_value: default value for the property specified
+@flags: flags for the property specified
+@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_int64 ##### -->
<!-- ##### FUNCTION g_param_spec_uint64 ##### -->
<para>
+Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64
+property.
+</para>
+<para>
+See g_param_spec_internal() for details on property names.
</para>
-@name:
-@nick:
-@blurb:
-@minimum:
-@maximum:
-@default_value:
-@flags:
-@Returns:
+@name: canonical name of the property specified
+@nick: nick name for the property specified
+@blurb: description of the property specified
+@minimum: minimum value for the property specified
+@maximum: maximum value for the property specified
+@default_value: default value for the property specified
+@flags: flags for the property specified
+@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_uint64 ##### -->
<!-- ##### FUNCTION g_param_spec_float ##### -->
<para>
+Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property.
+</para>
+<para>
+See g_param_spec_internal() for details on property names.
</para>
-@name:
-@nick:
-@blurb:
-@minimum:
-@maximum:
-@default_value:
-@flags:
-@Returns:
+@name: canonical name of the property specified
+@nick: nick name for the property specified
+@blurb: description of the property specified
+@minimum: minimum value for the property specified
+@maximum: maximum value for the property specified
+@default_value: default value for the property specified
+@flags: flags for the property specified
+@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_float ##### -->
<!-- ##### FUNCTION g_param_spec_double ##### -->
<para>
+Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE
+property.
+</para>
+<para>
+See g_param_spec_internal() for details on property names.
</para>
-@name:
-@nick:
-@blurb:
-@minimum:
-@maximum:
-@default_value:
-@flags:
-@Returns:
+@name: canonical name of the property specified
+@nick: nick name for the property specified
+@blurb: description of the property specified
+@minimum: minimum value for the property specified
+@maximum: maximum value for the property specified
+@default_value: default value for the property specified
+@flags: flags for the property specified
+@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_double ##### -->
<!-- ##### FUNCTION g_param_spec_boxed ##### -->
<para>
+Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED
+derived property.
+</para>
+<para>
+See g_param_spec_internal() for details on property names.
</para>
-@name:
-@nick:
-@blurb:
-@boxed_type:
-@flags:
-@Returns:
+@name: canonical name of the property specified
+@nick: nick name for the property specified
+@blurb: description of the property specified
+@boxed_type: %G_TYPE_BOXED derived type of this property
+@flags: flags for the property specified
+@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_boxed ##### -->
<!-- ##### FUNCTION g_param_spec_unichar ##### -->
<para>
+Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT
+property. #GValue structures for this property can be accessed with
+g_value_set_uint() and g_value_get_uint().
+</para>
+<para>
+See g_param_spec_internal() for details on property names.
</para>
-@name:
-@nick:
-@blurb:
-@default_value:
-@flags:
-@Returns:
+@name: canonical name of the property specified
+@nick: nick name for the property specified
+@blurb: description of the property specified
+@default_value: default value for the property specified
+@flags: flags for the property specified
+@Returns: a newly created parameter specification
<!-- ##### MACRO G_IS_PARAM_SPEC_VALUE_ARRAY ##### -->
<!-- ##### FUNCTION g_param_spec_value_array ##### -->
<para>
+Creates a new #GParamSpecValueArray instance specifying a
+%G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a %G_TYPE_BOXED
+type, as such, #GValue structures for this property can be accessed
+with g_value_set_boxed() and g_value_get_boxed().
+</para>
+<para>
+See g_param_spec_internal() for details on property names.
</para>
-@name:
-@nick:
-@blurb:
-@element_spec:
-@flags:
-@Returns:
+@name: canonical name of the property specified
+@nick: nick name for the property specified
+@blurb: description of the property specified
+@element_spec: a #GParamSpec describing the elements contained in
+ arrays of this property, may be %NULL
+@flags: flags for the property specified
+@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_signal_new ##### -->
<para>
-
+Creates a new signal. (This is usually done in the class initializer.)
+</para>
+<para>
+A signal name consists of segments consisting of ASCII letters and
+digits, separated by either the '-' or '_' character. The first
+character of a signal name must be a letter. Names which violate these
+rules lead to undefined behaviour of the GSignal system.
+</para>
+<para>
+When registering a signal and looking up a signal, either separator can
+be used, but they cannot be mixed.
</para>
-@signal_name:
-@itype:
-@signal_flags:
-@class_offset:
-@accumulator:
-@accu_data:
-@c_marshaller:
-@return_type:
-@n_params:
-@Varargs:
-@Returns:
+@signal_name: the name for the signal
+@itype: the type this signal pertains to. It will also pertain to
+ types which are derived from this type.
+@signal_flags: a combination of #GSignalFlags specifying detail of when
+ the default handler is to be invoked. You should at least specify
+ %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
+@class_offset: The offset of the function pointer in the class structure
+ for this type. Used to invoke a class method generically.
+@accumulator: the accumulator for this signal; may be %NULL.
+@accu_data: user data for the @accumulator.
+@c_marshaller: the function to translate arrays of parameter values to
+ signal emissions into C language callback invocations.
+@return_type: the type of return value, or #G_TYPE_NONE for a signal
+ without a return value.
+@n_params: the number of parameter types to follow.
+@Varargs: a list of types, one for each parameter.
+@Returns: the signal id
<!-- ##### FUNCTION g_signal_newv ##### -->
<para>
-
+Creates a new signal. (This is usually done in the class initializer.)
+</para>
+<para>
+See g_signal_new() for details on allowed signal names.
</para>
-@signal_name:
-@itype:
-@signal_flags:
-@class_closure:
-@accumulator:
-@accu_data:
-@c_marshaller:
-@return_type:
-@n_params:
-@param_types:
-@Returns:
+@signal_name: the name for the signal
+@itype: the type this signal pertains to. It will also pertain to
+ types which are derived from this type.
+@signal_flags: a combination of #GSignalFlags specifying detail of when
+ the default handler is to be invoked. You should at least specify
+ %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
+@class_closure: The closure to invoke on signal emission.
+@accumulator: the accumulator for this signal; may be %NULL.
+@accu_data: user data for the @accumulator.
+@c_marshaller: the function to translate arrays of parameter values to
+ signal emissions into C language callback invocations.
+@return_type: the type of return value, or #G_TYPE_NONE for a signal
+ without a return value.
+@n_params: the length of @param_types.
+@param_types: an array types, one for each parameter.
+@Returns: the signal id
<!-- ##### FUNCTION g_signal_new_valist ##### -->
<para>
-
+Creates a new signal. (This is usually done in the class initializer.)
+</para>
+<para>
+See g_signal_new() for details on allowed signal names.
</para>
-@signal_name:
-@itype:
-@signal_flags:
-@class_closure:
-@accumulator:
-@accu_data:
-@c_marshaller:
-@return_type:
-@n_params:
-@args:
-@Returns:
+@signal_name: the name for the signal
+@itype: the type this signal pertains to. It will also pertain to
+ types which are derived from this type.
+@signal_flags: a combination of #GSignalFlags specifying detail of when
+ the default handler is to be invoked. You should at least specify
+ %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
+@class_closure: The closure to invoke on signal emission.
+@accumulator: the accumulator for this signal; may be %NULL.
+@accu_data: user data for the @accumulator.
+@c_marshaller: the function to translate arrays of parameter values to
+ signal emissions into C language callback invocations.
+@return_type: the type of return value, or #G_TYPE_NONE for a signal
+ without a return value.
+@n_params: the number of parameter types in @args.
+@args: va_list of #GType, one for each parameter.
+@Returns: the signal id
<!-- ##### FUNCTION g_signal_query ##### -->
<para>
+Queries the signal system for in-depth information about a
+specific signal. This function will fill in a user-provided
+structure to hold signal-specific information. If an invalid
+signal id is passed in, the @signal_id member of the #GSignalQuery
+is 0. All members filled into the #GSignalQuery structure should
+be considered constant and have to be left untouched.
</para>
-@signal_id:
-@query:
+@signal_id: The signal id of the signal to query information for.
+@query: A user provided structure that is filled in with constant
+ values upon success.
<!-- ##### FUNCTION g_signal_lookup ##### -->
<para>
-
+Given the name of the signal and the type of object it connects to, gets
+the signal's identifying integer. Emitting the signal by number is
+somewhat faster than using the name each time.
+</para>
+<para>
+Also tries the ancestors of the given type.
+</para>
+<para>
+See g_signal_new() for details on allowed signal names.
</para>
-@name:
-@itype:
-@Returns:
+@name: the signal's name.
+@itype: the type that the signal operates on.
+@Returns: the signal's identifying number, or 0 if no signal was found.
<!-- ##### FUNCTION g_signal_name ##### -->
<para>
-
+Given the signal's identifier, finds its name.
+</para>
+<para>
+Two different signals may have the same name, if they have differing types.
</para>
-@signal_id:
-@Returns:
+@signal_id: the signal's identifying number.
+@Returns: the signal name, or %NULL if the signal number was invalid.
<!-- ##### FUNCTION g_signal_list_ids ##### -->
<para>
+Lists the signals by id that a certain instance or interface type
+created. Further information about the signals can be acquired through
+g_signal_query().
</para>
-@itype:
-@n_ids:
-@Returns:
+@itype: Instance or interface type.
+@n_ids: Location to store the number of signal ids for @itype.
+@Returns: Newly allocated array of signal IDs.
<!-- ##### FUNCTION g_signal_emit ##### -->
<para>
-
+Emits a signal.
+</para>
+<para>
+Note that g_signal_emit() resets the return value to the default
+if no handlers are connected, in contrast to g_signal_emitv().
</para>
-@instance:
-@signal_id:
-@detail:
-@Varargs:
+@instance: the instance the signal is being emitted on.
+@signal_id: the signal id
+@detail: the detail
+@Varargs: parameters to be passed to the signal, followed by a
+ location for the return value. If the return type of the signal
+ is #G_TYPE_NONE, the return value location can be omitted.
<!-- ##### FUNCTION g_signal_emit_by_name ##### -->
<para>
-
+Emits a signal.
+</para>
+<para>
+Note that g_signal_emit_by_name() resets the return value to the default
+if no handlers are connected, in contrast to g_signal_emitv().
</para>
-@instance:
-@detailed_signal:
-@Varargs:
+@instance: the instance the signal is being emitted on.
+@detailed_signal: a string of the form "signal-name::detail".
+@Varargs: parameters to be passed to the signal, followed by a
+ location for the return value. If the return type of the signal
+ is #G_TYPE_NONE, the return value location can be omitted.
<!-- ##### FUNCTION g_signal_emitv ##### -->
<para>
-
+Emits a signal.
+</para>
+<para>
+Note that g_signal_emitv() doesn't change @return_value if no handlers are
+connected, in contrast to g_signal_emit() and g_signal_emit_valist().
</para>
-@instance_and_params:
-@signal_id:
-@detail:
-@return_value:
+@instance_and_params: argument list for the signal emission. The first
+ element in the array is a #GValue for the instance the signal is
+ being emitted on. The rest are any arguments to be passed to the
+ signal.
+@signal_id: the signal id
+@detail: the detail
+@return_value: Location to store the return value of the signal emission.
<!-- ##### FUNCTION g_signal_emit_valist ##### -->
<para>
-
+Emits a signal.
+</para>
+<para>
+Note that g_signal_emit_valist() resets the return value to the default
+if no handlers are connected, in contrast to g_signal_emitv().
</para>
-@instance:
-@signal_id:
-@detail:
-@var_args:
+@instance: the instance the signal is being emitted on.
+@signal_id: the signal id
+@detail: the detail
+@var_args: a list of parameters to be passed to the signal, followed by a
+ location for the return value. If the return type of the signal
+ is #G_TYPE_NONE, the return value location can be omitted.
<!-- ##### MACRO g_signal_connect ##### -->
<!-- ##### FUNCTION g_signal_connect_object ##### -->
<para>
-
+ * This is similar to g_signal_connect_data(), but uses a closure which
+ * ensures that the object stays alive during the call to @c_handler.
</para>
+ * @instance: the instance to connect to.
+ * @detailed_signal: a string of the form "signal-name::detail".
+ * @c_handler: the #GCallback to connect.
+ * @gobject: the object to pass as data to @c_handler.
+ * @connect_flags: a combination of #GConnnectFlags.
+
@instance:
@detailed_signal:
@c_handler:
@gobject:
@connect_flags:
-@Returns:
+@Returns: the handler id.
<!-- ##### ENUM GConnectFlags ##### -->
<!-- ##### FUNCTION g_signal_connect_data ##### -->
<para>
-
+Connects a #GCallback function to a signal for a particular object.
</para>
-@instance:
-@detailed_signal:
-@c_handler:
-@data:
-@destroy_data:
-@connect_flags:
-@Returns:
+@instance: the instance to connect to.
+@detailed_signal: a string of the form "signal-name::detail".
+@c_handler: the #GCallback to connect.
+@data: data to pass to @c_handler calls.
+@destroy_data: a #GDestroyNotify for @data.
+@connect_flags: a combination of #GConnectFlags.
+@Returns: the handler id
<!-- ##### FUNCTION g_signal_connect_closure ##### -->
<para>
-
+Connects a closure to a signal for a particular object.
</para>
-@instance:
-@detailed_signal:
-@closure:
-@after:
-@Returns:
+@instance: the instance to connect to.
+@detailed_signal: a string of the form "signal-name::detail".
+@closure: the closure to connect.
+@after: whether the handler should be called before or after the
+ default handler of the signal.
+@Returns: the handler id
<!-- ##### FUNCTION g_signal_connect_closure_by_id ##### -->
<para>
-
+Connects a closure to a signal for a particular object.
</para>
-@instance:
-@signal_id:
-@detail:
-@closure:
-@after:
-@Returns:
+@instance: the instance to connect to.
+@signal_id: the id of the signal.
+@detail: the detail.
+@closure: the closure to connect.
+@after: whether the handler should be called before or after the
+ default handler of the signal.
+@Returns: the handler id
<!-- ##### FUNCTION g_signal_handler_block ##### -->
<para>
+Blocks a handler of an instance so it will not be called during
+any signal emissions unless it is unblocked again. Thus "blocking"
+a signal handler means to temporarily deactive it, a signal handler
+has to be unblocked exactly the same amount of times it has been
+blocked before to become active again.
+</para>
+<para>
+The @handler_id has to be a valid signal handler id, connected to a
+signal of @instance.
</para>
-@instance:
-@handler_id:
+@instance: The instance to block the signal handler of.
+@handler_id: Handler id of the handler to be blocked.
<!-- ##### FUNCTION g_signal_handler_unblock ##### -->
<para>
+Undoes the effect of a previous g_signal_handler_block() call.
+A blocked handler is skipped during signal emissions and will not be
+invoked, unblocking it (for exactly the amount of times it has been
+blocked before) reverts its "blocked" state, so the handler will be
+recognized by the signal system and is called upon future or currently
+ongoing signal emissions (since the order in which handlers are
+called during signal emissions is deterministic, whether the
+unblocked handler in question is called as part of a currently
+ongoing emission depends on how far that emission has proceeded
+yet).
+</para>
+<para>
+The @handler_id has to be a valid id of a signal handler that is
+connected to a signal of @instance and is currently blocked.
</para>
-@instance:
-@handler_id:
+@instance: The instance to unblock the signal handler of.
+@handler_id: Handler id of the handler to be unblocked.
<!-- ##### FUNCTION g_signal_handler_disconnect ##### -->
<para>
+Disconnects a handler from an instance so it will not be called during
+any future or currently ongoing emissions of the signal it has been
+connected to. The @handler_id becomes invalid and may be reused.
+</para>
+<para>
+The @handler_id has to be a valid signal handler id, connected to a
+signal of @instance.
</para>
-@instance:
-@handler_id:
+@instance: The instance to remove the signal handler from.
+@handler_id: Handler id of the handler to be disconnected.
<!-- ##### FUNCTION g_signal_handler_find ##### -->
<para>
+Finds the first signal handler that matches certain selection criteria.
+The criteria mask is passed as an OR-ed combination of #GSignalMatchType
+flags, and the criteria values are passed as arguments.
+The match @mask has to be non-0 for successful matches.
+If no handler was found, 0 is returned.
</para>
-@instance:
-@mask:
-@signal_id:
-@detail:
-@closure:
-@func:
-@data:
-@Returns:
+@instance: The instance owning the signal handler to be found.
+@mask: Mask indicating which of @signal_id, @detail, @closure, @func
+ and/or @data the handler has to match.
+@signal_id: Signal the handler has to be connected to.
+@detail: Signal detail the handler has to be connected to.
+@closure: The closure the handler will invoke.
+@func: The C closure callback of the handler (useless for non-C closures).
+@data: The closure data of the handler's closure.
+@Returns: A valid non-0 signal handler id for a successful match.
<!-- ##### FUNCTION g_signal_handlers_block_matched ##### -->
<para>
+Blocks all handlers on an instance that match a certain selection criteria.
+The criteria mask is passed as an OR-ed combination of #GSignalMatchType
+flags, and the criteria values are passed as arguments.
+Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
+or %G_SIGNAL_MATCH_DATA match flags is required for successful matches.
+If no handlers were found, 0 is returned, the number of blocked handlers
+otherwise.
</para>
-@instance:
-@mask:
-@signal_id:
-@detail:
-@closure:
-@func:
-@data:
-@Returns:
+@instance: The instance to block handlers from.
+@mask: Mask indicating which of @signal_id, @detail, @closure, @func
+ and/or @data the handlers have to match.
+@signal_id: Signal the handlers have to be connected to.
+@detail: Signal detail the handlers have to be connected to.
+@closure: The closure the handlers will invoke.
+@func: The C closure callback of the handlers (useless for non-C closures).
+@data: The closure data of the handlers' closures.
+@Returns: The amount of handlers that got blocked.
<!-- ##### FUNCTION g_signal_handlers_unblock_matched ##### -->
<para>
+Unblocks all handlers on an instance that match a certain selection
+criteria. The criteria mask is passed as an OR-ed combination of
+#GSignalMatchType flags, and the criteria values are passed as arguments.
+Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
+or %G_SIGNAL_MATCH_DATA match flags is required for successful matches.
+If no handlers were found, 0 is returned, the number of unblocked handlers
+otherwise. The match criteria should not apply to any handlers that are
+not currently blocked.
</para>
-@instance:
-@mask:
-@signal_id:
-@detail:
-@closure:
-@func:
-@data:
-@Returns:
+@instance: The instance to unblock handlers from.
+@mask: Mask indicating which of @signal_id, @detail, @closure, @func
+ and/or @data the handlers have to match.
+@signal_id: Signal the handlers have to be connected to.
+@detail: Signal detail the handlers have to be connected to.
+@closure: The closure the handlers will invoke.
+@func: The C closure callback of the handlers (useless for non-C closures).
+@data: The closure data of the handlers' closures.
+@Returns: The amount of handlers that got unblocked.
<!-- ##### FUNCTION g_signal_handlers_disconnect_matched ##### -->
<para>
+Disconnects all handlers on an instance that match a certain selection
+criteria. The criteria mask is passed as an OR-ed combination of
+#GSignalMatchType flags, and the criteria values are passed as arguments.
+Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
+or %G_SIGNAL_MATCH_DATA match flags is required for successful matches.
+If no handlers were found, 0 is returned, the number of disconnected
+handlers otherwise.
</para>
-@instance:
-@mask:
-@signal_id:
-@detail:
-@closure:
-@func:
-@data:
-@Returns:
+@instance: The instance to remove handlers from.
+@mask: Mask indicating which of @signal_id, @detail, @closure, @func
+ and/or @data the handlers have to match.
+@signal_id: Signal the handlers have to be connected to.
+@detail: Signal detail the handlers have to be connected to.
+@closure: The closure the handlers will invoke.
+@func: The C closure callback of the handlers (useless for non-C closures).
+@data: The closure data of the handlers' closures.
+@Returns: The amount of handlers that got disconnected.
<!-- ##### FUNCTION g_signal_handler_is_connected ##### -->
<para>
-
+Returns whether @handler_id is the id of a handler connected to @instance.
</para>
-@instance:
-@handler_id:
-@Returns:
+@instance: The instance where a signal handler is sought.
+@handler_id: the handler id.
+@Returns: whether @handler_id identifies a handler connected to @instance.
<!-- ##### MACRO g_signal_handlers_block_by_func ##### -->
<!-- ##### FUNCTION g_signal_has_handler_pending ##### -->
<para>
-
+Returns whether there are any handlers connected to @instance for the
+given signal id and detail.
+</para>
+<para>
+One example of when you might use this is when the arguments to the
+signal are difficult to compute. A class implementor may opt to not emit
+the signal if no one is attached anyway, thus saving the cost of building
+the arguments.
</para>
-@instance:
-@signal_id:
-@detail:
-@may_be_blocked:
-@Returns:
+@instance: the object whose signal handlers are sought.
+@signal_id: the signal id.
+@detail: the detail.
+@may_be_blocked: whether blocked handlers should count as match.
+@Returns: %TRUE if a handler is connected to the signal,
+ %FALSE otherwise.
<!-- ##### FUNCTION g_signal_stop_emission ##### -->
<para>
-
+Stops a signal's current emission.
+</para>
+<para>
+This will prevent the default method from running, if the signal was
+%G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after"
+flag).
+</para>
+<para>
+Prints a warning if used on a signal which isn't being emitted.
</para>
-@instance:
-@signal_id:
-@detail:
+@instance: the object whose signal handlers you wish to stop.
+@signal_id: the signal identifier, as returned by g_signal_lookup().
+@detail: the detail which the signal was emitted with.
<!-- ##### FUNCTION g_signal_stop_emission_by_name ##### -->
<para>
-
+Stops a signal's current emission.
+</para>
+<para>
+This is just like g_signal_stop_emission() except it will look up the
+signal id for you.
</para>
-@instance:
-@detailed_signal:
+@instance: the object whose signal handlers you wish to stop.
+@detailed_signal: a string of the form "signal-name::detail".
<!-- ##### FUNCTION g_signal_override_class_closure ##### -->
<para>
-
+Overrides the class closure (i.e. the default handler) for the given signal
+for emissions on instances of @instance_type. @instance_type must be derived
+from the type to which the signal belongs.
</para>
-@signal_id:
-@instance_type:
-@class_closure:
+@signal_id: the signal id
+@instance_type: the instance type on which to override the class closure
+ for the signal.
+@class_closure: the closure.
<!-- ##### FUNCTION g_signal_chain_from_overridden ##### -->
<para>
-
+Calls the original class closure of a signal. This function should only
+be called from an overridden class closure; see
+g_signal_override_class_closure().
</para>
-@instance_and_params:
-@return_value:
+@instance_and_params: the argument list of the signal emission. The first
+ element in the array is a #GValue for the instance the signal is being
+ emitted on. The rest are any arguments to be passed to the signal.
+@return_value: Location for the return value.
<!-- ##### FUNCTION g_signal_add_emission_hook ##### -->
<para>
-
+Adds an emission hook for a signal, which will get called for any emission
+of that signal, independent of the instance.
</para>
-@signal_id:
-@detail:
-@hook_func:
-@hook_data:
-@data_destroy:
-@Returns:
-<!-- # Unused Parameters # -->
-@quark:
+@signal_id: the signal identifier, as returned by g_signal_lookup().
+@detail: the detail on which to call the hook.
+@hook_func: a #GSignalEmissionHook function.
+@hook_data: user data for @hook_func.
+@data_destroy: a #GDestroyNotify for @hook_data.
+@Returns: the hook id, for later use with g_signal_remove_emission_hook().
<!-- ##### FUNCTION g_signal_remove_emission_hook ##### -->
<para>
-
+Deletes an emission hook.
</para>
-@signal_id:
-@hook_id:
+@signal_id: the id of the signal
+@hook_id: the id of the emission hook, as returned by
+g_signal_add_emission_hook()
<!-- ##### FUNCTION g_signal_parse_name ##### -->
<para>
+Internal function to parse a signal name into its @signal_id
+and @detail quark.
</para>
-@detailed_signal:
-@itype:
-@signal_id_p:
-@detail_p:
-@force_detail_quark:
-@Returns:
+@detailed_signal: a string of the form "signal-name::detail".
+@itype: The interface/instance type that introduced "signal-name".
+@signal_id_p: Location to store the signal id.
+@detail_p: Location to store the detail quark.
+@force_detail_quark: %TRUE forces creation of a #GQuark for the detail.
+@Returns: Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values.
<!-- ##### FUNCTION g_signal_get_invocation_hint ##### -->
<para>
-
+Returns the invocation hint of the innermost signal emission of instance.
</para>
-@instance:
-@Returns:
+@instance: the instance to query
+@Returns: the invocation hint of the innermost signal emission.
<!-- ##### FUNCTION g_signal_type_cclosure_new ##### -->