Migrating docs.

	* docs/reference/gobject/tmpl/signals.sgml:
	* gobject/gclosure.c:
	* gobject/gobject.c:
	* gobject/gsignal.c:
	* gobject/gsignal.h:
	  Migrating docs.


svn path=/trunk/; revision=7083

4 files changed, 818 insertions, 1 deletions

diff --git a/gobject/gclosure.c b/gobject/gclosure.c
index b1ca90e83..b16a81145 100644
--- a/gobject/gclosure.c
+++ b/gobject/gclosure.c
@@ -893,6 +893,18 @@ g_type_iface_meta_marshal (GClosure       *closure,
 		      callback);
 }
 
+/**
+ * g_signal_type_cclosure_new:
+ * @itype: the #GType identifier of an interface or classed type
+ * @struct_offset: the offset of the member function of @itype's class 
+ *  structure which is to be invoked by the new closure
+ * 
+ * Creates a new closure which invokes the function found at the offset
+ * @struct_offset in the class structure of the interface or classed type
+ * identified by @itype.
+ * 
+ * Returns: a new #GCClosure
+ */
 GClosure*
 g_signal_type_cclosure_new (GType    itype,
 			    guint    struct_offset)
diff --git a/gobject/gobject.c b/gobject/gobject.c
index aba014161..2de811060 100644
--- a/gobject/gobject.c
+++ b/gobject/gobject.c
@@ -2845,6 +2845,39 @@ g_value_dup_object (const GValue *value)
   return value->data[0].v_pointer ? g_object_ref (value->data[0].v_pointer) : NULL;
 }
 
+/**
+ * g_signal_connect_object:
+ * @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.
+ * 
+ *  This is similar to g_signal_connect_data(), but uses a closure which
+ *  ensures that the @gobject stays alive during the call to @c_handler
+ *  by temporarily adding a reference count to @gobject.
+ * 
+ *  Note that there is a bug in GObject that makes this function
+ *  much less useful than it might seem otherwise. Once @gobject is
+ *  disposed, the callback will no longer be called, but, the signal
+ *  handler is <emphasis>not</emphasis> currently disconnected. If the
+ *  @instance is itself being freed at the same time than this doesn't
+ *  matter, since the signal will automatically be removed, but
+ *  if @instance persists, then the signal handler will leak. You
+ *  should not remove the signal yourself because in a future versions of
+ *  GObject, the handler <emphasis>will</emphasis> automatically
+ *  be disconnected.
+ * 
+ *  It's possible to work around this problem in a way that will
+ *  continue to work with future versions of GObject by checking
+ *  that the signal handler is still connected before disconnected it:
+ * <informalexample><programlisting>
+ *  if (g_signal_handler_is_connected (instance, id))
+ *    g_signal_handler_disconnect (instance, id);
+ * </programlisting></informalexample>
+ * 
+ * Returns: the handler id.
+ */
 gulong
 g_signal_connect_object (gpointer      instance,
 			 const gchar  *detailed_signal,
diff --git a/gobject/gsignal.c b/gobject/gsignal.c
index 8ce1b6c6a..8a9a33c2f 100644
--- a/gobject/gsignal.c
+++ b/gobject/gsignal.c
@@ -19,7 +19,67 @@
  * this code is based on the original GtkSignal implementation
  * for the Gtk+ library by Peter Mattis <petm@xcf.berkeley.edu>
  */
-
+/**
+ * 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.
+ */
 /*
  * MT safe
  */
@@ -746,6 +806,20 @@ _g_signals_destroy (GType itype)
   SIGNAL_UNLOCK ();
 }
 
+/**
+ * g_signal_stop_emission:
+ * @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.
+ * 
+ * Stops a signal's current emission.
+ * 
+ * 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).
+ * 
+ * Prints a warning if used on a signal which isn't being emitted.
+ */
 void
 g_signal_stop_emission (gpointer instance,
                         guint    signal_id,
@@ -801,6 +875,20 @@ signal_finalize_hook (GHookList *hook_list,
     }
 }
 
+/**
+ * g_signal_add_emission_hook:
+ * @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.
+ * 
+ * Adds an emission hook for a signal, which will get called for any emission
+ * of that signal, independent of the instance. This is possible only
+ * for signals which don't have #G_SIGNAL_NO_HOOKS flag set.
+ * 
+ * Returns: the hook id, for later use with g_signal_remove_emission_hook().
+ */
 gulong
 g_signal_add_emission_hook (guint               signal_id,
 			    GQuark              detail,
@@ -856,6 +944,14 @@ g_signal_add_emission_hook (guint               signal_id,
   return hook->hook_id;
 }
 
+/**
+ * g_signal_remove_emission_hook:
+ * @signal_id: the id of the signal
+ * @hook_id: the id of the emission hook, as returned by 
+ *  g_signal_add_emission_hook()
+ * 
+ * Deletes an emission hook.
+ */
 void
 g_signal_remove_emission_hook (guint  signal_id,
 			       gulong hook_id)
@@ -918,6 +1014,19 @@ signal_parse_name (const gchar *name,
   return signal_id;
 }
 
+/**
+ * g_signal_parse_name:
+ * @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.
+ * 
+ * Internal function to parse a signal name into its @signal_id
+ * and @detail quark.
+ * 
+ * Returns: Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values.
+ */
 gboolean
 g_signal_parse_name (const gchar *detailed_signal,
 		     GType        itype,
@@ -949,6 +1058,16 @@ g_signal_parse_name (const gchar *detailed_signal,
   return TRUE;
 }
 
+/**
+ * g_signal_stop_emission_by_name:
+ * @instance: the object whose signal handlers you wish to stop.
+ * @detailed_signal: a string of the form "signal-name::detail".
+ * 
+ * Stops a signal's current emission.
+ * 
+ * This is just like g_signal_stop_emission() except it will look up the 
+ * signal id for you.
+ */
 void
 g_signal_stop_emission_by_name (gpointer     instance,
 				const gchar *detailed_signal)
@@ -994,6 +1113,21 @@ g_signal_stop_emission_by_name (gpointer     instance,
   SIGNAL_UNLOCK ();
 }
 
+/**
+ * g_signal_lookup:
+ * @name: the signal's name.
+ * @itype: the type that the signal operates on.
+ * 
+ * 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.
+ * 
+ * Also tries the ancestors of the given type.
+ * 
+ * See g_signal_new() for details on allowed signal names.
+ * 
+ * Returns: the signal's identifying number, or 0 if no signal was found.
+ */
 guint
 g_signal_lookup (const gchar *name,
                  GType        itype)
@@ -1022,6 +1156,17 @@ g_signal_lookup (const gchar *name,
   return signal_id;
 }
 
+/**
+ * g_signal_list_ids:
+ * @itype: Instance or interface type.
+ * @n_ids: Location to store the number of signal ids for @itype.
+ * 
+ * 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().
+ * 
+ * Returns: Newly allocated array of signal IDs.
+ */
 guint*
 g_signal_list_ids (GType  itype,
 		   guint *n_ids)
@@ -1069,6 +1214,16 @@ g_signal_list_ids (GType  itype,
   return (guint*) g_array_free (result, FALSE);
 }
 
+/**
+ * g_signal_name:
+ * @signal_id: the signal's identifying number.
+ * 
+ * Given the signal's identifier, finds its name.
+ * 
+ * Two different signals may have the same name, if they have differing types.
+ * 
+ * Returns: the signal name, or %NULL if the signal number was invalid.
+ */
 G_CONST_RETURN gchar*
 g_signal_name (guint signal_id)
 {
@@ -1083,6 +1238,19 @@ g_signal_name (guint signal_id)
   return (char*) name;
 }
 
+/**
+ * g_signal_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.
+ * 
+ * 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.
+ */
 void
 g_signal_query (guint         signal_id,
 		GSignalQuery *query)
@@ -1108,6 +1276,38 @@ g_signal_query (guint         signal_id,
   SIGNAL_UNLOCK ();
 }
 
+/**
+ * g_signal_new:
+ * @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. Pass 0 to
+ *  not associate a class method with this signal.
+ * @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.
+ * @...: a list of types, one for each parameter.
+ * 
+ * Creates a new signal. (This is usually done in the class initializer.)
+ * 
+ * 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. 
+ * 
+ * When registering a signal and looking up a signal, either separator can
+ * be used, but they cannot be mixed. 
+ * 
+ * Returns: the signal id
+ */
 guint
 g_signal_new (const gchar	 *signal_name,
 	      GType		  itype,
@@ -1210,6 +1410,30 @@ signal_add_class_closure (SignalNode *node,
     g_closure_set_marshal (closure, node->c_marshaller);
 }
 
+/**
+ * g_signal_newv:
+ * @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; may be %NULL.
+ * @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.
+ * 
+ * Creates a new signal. (This is usually done in the class initializer.)
+ * 
+ * See g_signal_new() for details on allowed signal names.
+ * 
+ * Returns: the signal id
+ */
 guint
 g_signal_newv (const gchar       *signal_name,
                GType              itype,
@@ -1344,6 +1568,30 @@ g_signal_newv (const gchar       *signal_name,
   return signal_id;
 }
 
+/**
+ * g_signal_new_valist:
+ * @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; may be %NULL.
+ * @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.
+ * 
+ * Creates a new signal. (This is usually done in the class initializer.)
+ * 
+ * See g_signal_new() for details on allowed signal names.
+ * 
+ * Returns: the signal id
+ */
 guint
 g_signal_new_valist (const gchar       *signal_name,
                      GType              itype,
@@ -1433,6 +1681,17 @@ signal_destroy_R (SignalNode *signal_node)
   SIGNAL_LOCK ();
 }
 
+/**
+ * g_signal_override_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.
+ * 
+ * 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.
+ */
 void
 g_signal_override_class_closure (guint     signal_id,
 				 GType     instance_type,
@@ -1459,6 +1718,17 @@ g_signal_override_class_closure (guint     signal_id,
   SIGNAL_UNLOCK ();
 }
 
+/**
+ * g_signal_chain_from_overridden:
+ * @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.
+ * 
+ * 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().
+ */
 void
 g_signal_chain_from_overridden (const GValue *instance_and_params,
 				GValue       *return_value)
@@ -1518,6 +1788,14 @@ g_signal_chain_from_overridden (const GValue *instance_and_params,
   SIGNAL_UNLOCK ();
 }
 
+/**
+ * g_signal_get_invocation_hint:
+ * @instance: the instance to query
+ * 
+ * Returns the invocation hint of the innermost signal emission of instance. 
+ * 
+ * Returns: the invocation hint of the innermost signal emission.
+ */
 GSignalInvocationHint*
 g_signal_get_invocation_hint (gpointer instance)
 {
@@ -1532,6 +1810,19 @@ g_signal_get_invocation_hint (gpointer instance)
   return emission ? &emission->ihint : NULL;
 }
 
+/**
+ * g_signal_connect_closure_by_id:
+ * @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.
+ * 
+ * Connects a closure to a signal for a particular object.
+ * 
+ * Returns: the handler id
+ */
 gulong
 g_signal_connect_closure_by_id (gpointer  instance,
 				guint     signal_id,
@@ -1574,6 +1865,18 @@ g_signal_connect_closure_by_id (gpointer  instance,
   return handler_seq_no;
 }
 
+/**
+ * g_signal_connect_closure:
+ * @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.
+ * 
+ * Connects a closure to a signal for a particular object.
+ * 
+ * Returns: the handler id
+ */
 gulong
 g_signal_connect_closure (gpointer     instance,
 			  const gchar *detailed_signal,
@@ -1620,6 +1923,23 @@ g_signal_connect_closure (gpointer     instance,
   return handler_seq_no;
 }
 
+/**
+ * g_signal_connect_data:
+ * @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 #GClosureNotify for @data.
+ * @connect_flags: a combination of #GConnectFlags.
+ * 
+ * Connects a #GCallback function to a signal for a particular object. Similar
+ * to g_signal_connect(), but allows to provide a #GClosureNotify for the data
+ * which will be called when the signal handler is disconnected and no longer
+ * used. Specify @connect_flags if you need <literal>..._after()</literal> or
+ * <literal>..._swapped()</literal> variants of this function.
+ * 
+ * Returns: the handler id
+ */
 gulong
 g_signal_connect_data (gpointer       instance,
 		       const gchar   *detailed_signal,
@@ -1672,6 +1992,20 @@ g_signal_connect_data (gpointer       instance,
   return handler_seq_no;
 }
 
+/**
+ * g_signal_handler_block:
+ * @instance: The instance to block the signal handler of.
+ * @handler_id: Handler id of the handler to be blocked.
+ * 
+ * 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.
+ * 
+ * The @handler_id has to be a valid signal handler id, connected to a 
+ * signal of @instance.
+ */
 void
 g_signal_handler_block (gpointer instance,
                         gulong   handler_id)
@@ -1696,6 +2030,25 @@ g_signal_handler_block (gpointer instance,
   SIGNAL_UNLOCK ();
 }
 
+/**
+ * g_signal_handler_unblock:
+ * @instance: The instance to unblock the signal handler of.
+ * @handler_id: Handler id of the handler to be unblocked.
+ * 
+ * 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).
+ * 
+ * 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.
+ */
 void
 g_signal_handler_unblock (gpointer instance,
                           gulong   handler_id)
@@ -1719,6 +2072,18 @@ g_signal_handler_unblock (gpointer instance,
   SIGNAL_UNLOCK ();
 }
 
+/**
+ * g_signal_handler_disconnect:
+ * @instance: The instance to remove the signal handler from.
+ * @handler_id: Handler id of the handler to be disconnected.
+ * 
+ * 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.
+ * 
+ * The @handler_id has to be a valid signal handler id, connected to a 
+ * signal of @instance.
+ */
 void
 g_signal_handler_disconnect (gpointer instance,
                              gulong   handler_id)
@@ -1742,6 +2107,15 @@ g_signal_handler_disconnect (gpointer instance,
   SIGNAL_UNLOCK ();
 }
 
+/**
+ * g_signal_handler_is_connected:
+ * @instance: The instance where a signal handler is sought.
+ * @handler_id: the handler id.
+ * 
+ * Returns whether @handler_id is the id of a handler connected to @instance.
+ * 
+ * Returns: whether @handler_id identifies a handler connected to @instance.
+ */
 gboolean
 g_signal_handler_is_connected (gpointer instance,
 			       gulong   handler_id)
@@ -1801,6 +2175,25 @@ g_signal_handlers_destroy (gpointer instance)
   SIGNAL_UNLOCK ();
 }
 
+/**
+ * g_signal_handler_find:
+ * @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.
+ * 
+ * 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.
+ * 
+ * Returns: A valid non-0 signal handler id for a successful match.
+ */
 gulong
 g_signal_handler_find (gpointer         instance,
                        GSignalMatchType mask,
@@ -1862,6 +2255,27 @@ signal_handlers_foreach_matched_R (gpointer         instance,
   return n_handlers;
 }
 
+/**
+ * g_signal_handlers_block_matched:
+ * @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.
+ * 
+ * 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.
+ * 
+ * Returns: The number of handlers that matched.
+ */
 guint
 g_signal_handlers_block_matched (gpointer         instance,
 				 GSignalMatchType mask,
@@ -1888,6 +2302,28 @@ g_signal_handlers_block_matched (gpointer         instance,
   return n_handlers;
 }
 
+/**
+ * g_signal_handlers_unblock_matched:
+ * @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.
+ * 
+ * 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.
+ * 
+ * Returns: The number of handlers that matched.
+ */
 guint
 g_signal_handlers_unblock_matched (gpointer         instance,
 				   GSignalMatchType mask,
@@ -1914,6 +2350,27 @@ g_signal_handlers_unblock_matched (gpointer         instance,
   return n_handlers;
 }
 
+/**
+ * g_signal_handlers_disconnect_matched:
+ * @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.
+ * 
+ * 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.
+ * 
+ * Returns: The number of handlers that matched.
+ */
 guint
 g_signal_handlers_disconnect_matched (gpointer         instance,
 				      GSignalMatchType mask,
@@ -1940,6 +2397,24 @@ g_signal_handlers_disconnect_matched (gpointer         instance,
   return n_handlers;
 }
 
+/**
+ * g_signal_has_handler_pending:
+ * @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 whether there are any handlers connected to @instance for the
+ * given signal id and detail.
+ * 
+ * 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.
+ * 
+ * Returns: %TRUE if a handler is connected to the signal, 
+ *  %FALSE otherwise.
+ */
 gboolean
 g_signal_has_handler_pending (gpointer instance,
 			      guint    signal_id,
@@ -2023,6 +2498,21 @@ signal_check_skip_emission (SignalNode *node,
   return TRUE;
 }
 
+/**
+ * g_signal_emitv:
+ * @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.
+ * 
+ * Emits a signal. 
+ * 
+ * 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().
+ */
 void
 g_signal_emitv (const GValue *instance_and_params,
 		guint         signal_id,
@@ -2111,6 +2601,20 @@ g_signal_emitv (const GValue *instance_and_params,
   signal_emit_unlocked_R (node, detail, instance, return_value, instance_and_params);
 }
 
+/**
+ * g_signal_emit_valist:
+ * @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.
+ * 
+ * Emits a signal. 
+ * 
+ * Note that g_signal_emit_valist() resets the return value to the default
+ * if no handlers are connected, in contrast to g_signal_emitv().
+ */
 void
 g_signal_emit_valist (gpointer instance,
 		      guint    signal_id,
@@ -2231,6 +2735,20 @@ g_signal_emit_valist (gpointer instance,
     g_free (free_me);
 }
 
+/**
+ * g_signal_emit:
+ * @instance: the instance the signal is being emitted on.
+ * @signal_id: the signal id
+ * @detail: the detail
+ * @...: 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.
+ * 
+ * Emits a signal. 
+ * 
+ * Note that g_signal_emit() resets the return value to the default
+ * if no handlers are connected, in contrast to g_signal_emitv().
+ */
 void
 g_signal_emit (gpointer instance,
 	       guint    signal_id,
@@ -2244,6 +2762,19 @@ g_signal_emit (gpointer instance,
   va_end (var_args);
 }
 
+/**
+ * g_signal_emit_by_name:
+ * @instance: the instance the signal is being emitted on.
+ * @detailed_signal: a string of the form "signal-name::detail".
+ * @...: 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.
+ * 
+ * Emits a signal. 
+ * 
+ * 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().
+ */
 void
 g_signal_emit_by_name (gpointer     instance,
 		       const gchar *detailed_signal,
@@ -2590,6 +3121,24 @@ type_debug_name (GType type)
     return "<invalid>";
 }
 
+/**
+ * g_signal_accumulator_true_handled:
+ * @ihint: standard #GSignalAccumulator parameter
+ * @return_accu: standard #GSignalAccumulator parameter
+ * @handler_return: standard #GSignalAccumulator parameter
+ * @dummy: standard #GSignalAccumulator parameter
+ * 
+ * A predefined #GSignalAccumulator for signals that return a
+ * boolean values. The behavior that this accumulator gives is
+ * that a return of %TRUE stops the signal emission: no further
+ * callbacks will be invoked, while a return of %FALSE allows
+ * the emission to coninue. The idea here is that a %TRUE return
+ * indicates that the callback <emphasis>handled</emphasis> the signal,
+ * and no further handling is needed.
+ * 
+ * Since: 2.4
+ * Returns: standard #GSignalAccumulator result
+ */
 gboolean
 g_signal_accumulator_true_handled (GSignalInvocationHint *ihint,
 				   GValue                *return_accu,
diff --git a/gobject/gsignal.h b/gobject/gsignal.h
index 61345dcba..1f703846f 100644
--- a/gobject/gsignal.h
+++ b/gobject/gsignal.h
@@ -33,11 +33,57 @@ G_BEGIN_DECLS
 /* --- typedefs --- */
 typedef struct _GSignalQuery		 GSignalQuery;
 typedef struct _GSignalInvocationHint	 GSignalInvocationHint;
+/**
+ * GSignalCMarshaller:
+ * 
+ * This is the signature of marshaller functions, required to marshall
+ * arrays of parameter values to signal emissions into C language callback
+ * invocations. It is merely an alias to #GClosureMarshal since the #GClosure
+ * mechanism takes over responsibility of actual function invocation for the
+ * signal system.
+ */
 typedef GClosureMarshal			 GSignalCMarshaller;
+/**
+ * GSignalEmissionHook:
+ * @ihint: Signal invocation hint, see #GSignalInvocationHint.
+ * @n_param_values: the number of parameters to the function, including
+ *  the instance on which the signal was emitted.
+ * @param_values: the instance on which the signal was emitted, followed by the 
+ *  parameters of the emission.
+ * @data: user data associated with the hook.
+ * 
+ * A simple function pointer to get invoked when the signal is emitted. This 
+ * allows you to tie a hook to the signal type, so that it will trap all 
+ * emissions of that signal, from any object.
+ * 
+ * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
+ * 
+ * Returns: whether it wants to stay connected. If it returns %FALSE, the signal 
+ *  hook is disconnected (and destroyed).
+ */
 typedef gboolean (*GSignalEmissionHook) (GSignalInvocationHint *ihint,
 					 guint			n_param_values,
 					 const GValue	       *param_values,
 					 gpointer		data);
+/**
+ * GSignalAccumulator:
+ * @ihint: Signal invocation hint, see #GSignalInvocationHint.
+ * @return_accu: Accumulator to collect callback return values in, this
+ *  is the return value of the current signal emission.
+ * @handler_return: A #GValue holding the return value of the signal handler.
+ * @data: Callback data that was specified when creating the signal.
+ * 
+ * The signal accumulator is a special callback function that can be used
+ * to collect return values of the various callbacks that are called
+ * during a signal emission. The signal accumulator is specified at signal
+ * creation time, if it is left %NULL, no accumulation of callback return
+ * values is performed. The return value of signal emissions is then the
+ * value returned by the last callback.
+ * 
+ * Returns: The accumulator function returns whether the signal emission
+ *  should be aborted. Returning %FALSE means to abort the
+ *  current emission and %TRUE is returned for continuation.
+ */
 typedef gboolean (*GSignalAccumulator)	(GSignalInvocationHint *ihint,
 					 GValue		       *return_accu,
 					 const GValue	       *handler_return,
@@ -45,6 +91,28 @@ typedef gboolean (*GSignalAccumulator)	(GSignalInvocationHint *ihint,
 
 
 /* --- run, match and connect types --- */
+/**
+ * GSignalFlags:
+ * @G_SIGNAL_RUN_FIRST: Invoke the object method handler in the first emission stage.
+ * @G_SIGNAL_RUN_LAST: Invoke the object method handler in the third emission stage.
+ * @G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage.
+ * @G_SIGNAL_NO_RECURSE: Signals being emitted for an object while currently being in
+ *  emission for this very object will not be emitted recursively,
+ *  but instead cause the first emission to be restarted.
+ * @G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name
+ *  upon handler connections and emissions.
+ * @G_SIGNAL_ACTION: Action signals are signals that may freely be emitted on alive
+ *  objects from user code via g_signal_emit() and friends, without
+ *  the need of being embedded into extra code that performs pre or
+ *  post emission adjustments on the object. They can also be thought
+ *  of as object methods which can be called generically by 
+ *  third-party code.
+ * @G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal.
+ * 
+ * The signal flags are used to specify a signal's behaviour, the overall
+ * signal description outlines how especially the RUN flags control the
+ * stages of a signal emission.
+ */
 typedef enum
 {
   G_SIGNAL_RUN_FIRST	= 1 << 0,
@@ -55,12 +123,40 @@ typedef enum
   G_SIGNAL_ACTION	= 1 << 5,
   G_SIGNAL_NO_HOOKS	= 1 << 6
 } GSignalFlags;
+/**
+ * G_SIGNAL_FLAGS_MASK:
+ * 
+ * A mask for all #GSignalFlags bits.
+ */
 #define G_SIGNAL_FLAGS_MASK  0x7f
+/**
+ * GConnectFlags:
+ * @G_CONNECT_AFTER: whether the handler should be called before or after the 
+ *  default handler of the signal.
+ * @G_CONNECT_SWAPPED: whether the instance and data should be swapped when
+ *  calling the handler.
+ * 
+ * The connection flags are used to specify the behaviour of a signal's 
+ * connection.
+ */
 typedef enum
 {
   G_CONNECT_AFTER	= 1 << 0,
   G_CONNECT_SWAPPED	= 1 << 1
 } GConnectFlags;
+/**
+ * GSignalMatchType:
+ * @G_SIGNAL_MATCH_ID: The signal id must be equal.
+ * @G_SIGNAL_MATCH_DETAIL: The signal detail be equal.
+ * @G_SIGNAL_MATCH_CLOSURE: The closure must be the same.
+ * @G_SIGNAL_MATCH_FUNC: The C closure callback must be the same.
+ * @G_SIGNAL_MATCH_DATA: The closure data must be the same.
+ * @G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched.
+ * 
+ * The match types specify what g_signal_handlers_block_matched(),
+ * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched()
+ * match signals by.
+ */
 typedef enum
 {
   G_SIGNAL_MATCH_ID	   = 1 << 0,
@@ -70,17 +166,74 @@ typedef enum
   G_SIGNAL_MATCH_DATA	   = 1 << 4,
   G_SIGNAL_MATCH_UNBLOCKED = 1 << 5
 } GSignalMatchType;
+/**
+ * G_SIGNAL_MATCH_MASK:
+ * 
+ * A mask for all #GSignalMatchType bits.
+ */
 #define G_SIGNAL_MATCH_MASK  0x3f
+/**
+ * G_SIGNAL_TYPE_STATIC_SCOPE:
+ * 
+ * This macro flags signal argument types for which the signal system may 
+ * assume that instances thereof remain persistent across all signal emissions
+ * they are used in. This is only useful for non ref-counted, value-copy types.
+ * 
+ * To flag a signal argument in this way, add 
+ * <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument
+ * of g_signal_new().
+ * |[
+ * g_signal_new ("size_request",
+ *   G_TYPE_FROM_CLASS (gobject_class),
+ * 	 G_SIGNAL_RUN_FIRST,
+ * 	 G_STRUCT_OFFSET (GtkWidgetClass, size_request),
+ * 	 NULL, NULL,
+ * 	 _gtk_marshal_VOID__BOXED,
+ * 	 G_TYPE_NONE, 1,
+ * 	 GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
+ * ]|
+ */
 #define	G_SIGNAL_TYPE_STATIC_SCOPE (G_TYPE_FLAG_RESERVED_ID_BIT)
 
 
 /* --- signal information --- */
+/**
+ * GSignalInvocationHint:
+ * @signal_id: The signal id of the signal invoking the callback
+ * @detail: The detail passed on for this emission
+ * @run_type: The stage the signal emission is currently in, this
+ *  field will contain one of %G_SIGNAL_RUN_FIRST,
+ *  %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP.
+ * 
+ * The #GSignalInvocationHint structure is used to pass on additional information
+ * to callbacks during a signal emission.
+ */
 struct _GSignalInvocationHint
 {
   guint		signal_id;
   GQuark	detail;
   GSignalFlags	run_type;
 };
+/**
+ * GSignalQuery:
+ * @signal_id: The signal id of the signal being queried, or 0 if the
+ *  signal to be queried was unknown.
+ * @signal_name: The signal name.
+ * @itype: The interface/instance type that this signal can be emitted for.
+ * @signal_flags: The signal flags as passed in to g_signal_new().
+ * @return_type: The return type for user callbacks.
+ * @n_params: The number of parameters that user callbacks take.
+ * @param_types: The individual parameter types for user callbacks, note that the
+ *  effective callback signature is:
+ *  <programlisting>
+ *  @return_type callback (#gpointer     data1,
+ *  [#param_types param_names,]
+ *  #gpointer     data2);
+ *  </programlisting>
+ * 
+ * A structure holding in-depth information for a specific signal. It is
+ * filled in by the g_signal_query() function.
+ */
 struct _GSignalQuery
 {
   guint		signal_id;
@@ -236,20 +389,90 @@ void	g_signal_chain_from_overridden	      (const GValue      *instance_and_param
 
 
 /* --- convenience --- */
+/**
+ * g_signal_connect:
+ * @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.
+ * 
+ * Connects a #GCallback function to a signal for a particular object.
+ * 
+ * The handler will be called before the default handler of the signal.
+ * 
+ * Returns: the handler id
+ */
 #define g_signal_connect(instance, detailed_signal, c_handler, data) \
     g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, (GConnectFlags) 0)
+/**
+ * g_signal_connect_after:
+ * @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.
+ * 
+ * Connects a #GCallback function to a signal for a particular object.
+ * 
+ * The handler will be called after the default handler of the signal.
+ * 
+ * Returns: the handler id
+ */
 #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)
+/**
+ * g_signal_connect_swapped:
+ * @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.
+ * 
+ * Connects a #GCallback function to a signal for a particular object.
+ * 
+ * The instance on which the signal is emitted and @data will be swapped when 
+ * calling the handler.
+ * 
+ * Returns: the handler id
+ */
 #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)
+/**
+ * g_signal_handlers_disconnect_by_func:
+ * @instance: The instance to remove handlers from.
+ * @func: The C closure callback of the handlers (useless for non-C closures).
+ * @data: The closure data of the handlers' closures.
+ * 
+ * Disconnects all handlers on an instance that match @func and @data.
+ * 
+ * Returns: The number of handlers that matched.
+ */
 #define	g_signal_handlers_disconnect_by_func(instance, func, data)						\
     g_signal_handlers_disconnect_matched ((instance),								\
 					  (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA),	\
 					  0, 0, NULL, (func), (data))
+/**
+ * g_signal_handlers_block_by_func:
+ * @instance: The instance to block handlers from.
+ * @func: The C closure callback of the handlers (useless for non-C closures).
+ * @data: The closure data of the handlers' closures.
+ * 
+ * Blocks all handlers on an instance that match @func and @data.
+ * 
+ * Returns: The number of handlers that matched.
+ */
 #define	g_signal_handlers_block_by_func(instance, func, data)							\
     g_signal_handlers_block_matched      ((instance),								\
 				          (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA),	\
 				          0, 0, NULL, (func), (data))
+/**
+ * g_signal_handlers_unblock_by_func:
+ * @instance: The instance to unblock handlers from.
+ * @func: The C closure callback of the handlers (useless for non-C closures).
+ * @data: The closure data of the handlers' closures.
+ * 
+ * Unblocks all handlers on an instance that match @func and @data.
+ * 
+ * Returns: The number of handlers that matched.
+ */
 #define	g_signal_handlers_unblock_by_func(instance, func, data)							\
     g_signal_handlers_unblock_matched    ((instance),								\
 				          (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA),	\