Move all docs out-of-line. Boy, what a waste of time.

2003-02-07  Matthias Clasen  <maclas@gmx.de>

	* gobject/tmpl/gtypemodule.sgml:
	* gobject/tmpl/gtype.sgml:
	* gobject/tmpl/gclosure.sgml:
	* gobject/tmpl/param_value_types.sgml:
	* gobject/tmpl/gparamspec.sgml:
	* gobject/tmpl/objects.sgml:
	* gobject/tmpl/signals.sgml: Move all docs out-of-line. Boy, what
	a waste of time.

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 73d3856..300c0f3 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,14 @@
+2003-02-07  Matthias Clasen  <maclas@gmx.de>
+
+       * gobject/tmpl/gtypemodule.sgml: 
+       * gobject/tmpl/gtype.sgml: 
+       * gobject/tmpl/gclosure.sgml: 
+       * gobject/tmpl/param_value_types.sgml: 
+       * gobject/tmpl/gparamspec.sgml: 
+       * gobject/tmpl/objects.sgml: 
+       * gobject/tmpl/signals.sgml: Move all docs out-of-line. Boy, what
+       a waste of time.
+
 2003-01-21  Matthias Clasen  <maclas@gmx.de>
 
        * glib/tmpl/strings.sgml: Document the return value of g_string_free().

diff --git a/docs/reference/gobject/tmpl/gclosure.sgml b/docs/reference/gobject/tmpl/gclosure.sgml
index 97210ac..9f52377 100644 (file)
--- a/docs/reference/gobject/tmpl/gclosure.sgml
+++ b/docs/reference/gobject/tmpl/gclosure.sgml
@@ -319,11 +319,16 @@ atfer this function, unles g_closure_ref() was called beforehand.
 
 <!-- ##### FUNCTION g_source_set_closure ##### -->
 <para>
-
+Set the callback for a source as a #GClosure.
+</para>
+<para>
+If the source is not one of the standard GLib types, the @closure_callback
+and @closure_marshal fields of the GSourceFuncs structure must have been
+filled in with pointers to appropriate functions.
 </para>
 
-@source: 
-@closure: 
+@source: the source
+@closure: a #GClosure
 
 
 <!-- ##### MACRO G_TYPE_IO_CHANNEL ##### -->

diff --git a/docs/reference/gobject/tmpl/gobject-unused.sgml b/docs/reference/gobject/tmpl/gobject-unused.sgml
index aa57654..ec1cdb1 100644 (file)
--- a/docs/reference/gobject/tmpl/gobject-unused.sgml
+++ b/docs/reference/gobject/tmpl/gobject-unused.sgml
@@ -196,6 +196,13 @@ Shift value used in converting numbers to type IDs.
 @closure: 
 @Returns: 
 
+<!-- ##### FUNCTION g_signal_handlers_destroy ##### -->
+<para>
+
+</para>
+
+@instance: 
+
 <!-- ##### MACRO g_signal_newc ##### -->
 <para>
 

diff --git a/docs/reference/gobject/tmpl/gparamspec.sgml b/docs/reference/gobject/tmpl/gparamspec.sgml
index e03618a..1490fc0 100644 (file)
--- a/docs/reference/gobject/tmpl/gparamspec.sgml
+++ b/docs/reference/gobject/tmpl/gparamspec.sgml
@@ -311,15 +311,26 @@ if @value1 is found to be less than, equal to or greater than @value2, respectiv
 
 <!-- ##### FUNCTION g_param_spec_internal ##### -->
 <para>
-
+Creates a new #GParamSpec instance.
+</para>
+<para>
+A property name consists of segments consisting of ASCII letters and
+digits, separated by either the '-' or '_' character. The first
+character of a property name must be a letter. Names which violate these
+rules lead to undefined behaviour. 
+</para>
+<para>
+When creating and looking up a #GParamSpec, either separator can be used, 
+but they cannot be mixed. Using '-' is considerably more efficient and in 
+fact required when using property names as detail strings for signals.
 </para>
 
-@param_type: 
-@name: 
-@nick: 
-@blurb: 
-@flags: 
-@Returns: 
+@param_type: the #GType for the property; must be derived from #G_TYPE_PARAM
+@name: the canonical name of the property
+@nick: the nickname of the property
+@blurb: a short description of the property
+@flags: a combination of #GParamFlags
+@Returns: a newly allocated #GParamSpec instance
 
 
 <!-- ##### STRUCT GParamSpecTypeInfo ##### -->

diff --git a/docs/reference/gobject/tmpl/gtype.sgml b/docs/reference/gobject/tmpl/gtype.sgml
index 9b76330..2304a66 100644 (file)
--- a/docs/reference/gobject/tmpl/gtype.sgml
+++ b/docs/reference/gobject/tmpl/gtype.sgml
@@ -707,11 +707,16 @@ class conforms.
 
 <!-- ##### FUNCTION g_type_interface_peek_parent ##### -->
 <para>
-
+Returns the corresponding #GTypeInterface structure of the parent type
+of the instance type to which @g_iface belongs. This is useful when 
+deriving the implementation of an interface from the parent type and 
+then possibly overriding some methods. 
 </para>
 
-@g_iface: 
-@Returns: 
+@g_iface: A #GTypeInterface structure.
+@Returns: The corresponding #GTypeInterface structure of the parent type
+   of the instance type to which @g_iface belongs, or %NULL if the parent type
+   doesn't conform to the interface.
 
 
 <!-- ##### FUNCTION g_type_children ##### -->
@@ -739,40 +744,50 @@ g_free()ed after use.
 
 <!-- ##### FUNCTION g_type_interface_prerequisites ##### -->
 <para>
-
+Returns the prerequisites of an interfaces type.
 </para>
 
-@interface_type: 
-@n_prerequisites: 
-@Returns: 
+@interface_type: an interface type
+@n_prerequisites: location to return the number of prerequisites, or %NULL
+@Returns: a newly-allocated zero-terminated array of #GType containing 
+   the prerequisites of @interface_type
+<!-- # Unused Parameters # -->
+@Since: 2.2
 
 
 <!-- ##### FUNCTION g_type_set_qdata ##### -->
 <para>
-
+Attaches arbitrary data to a type.
 </para>
 
-@type: 
-@quark: 
-@data: 
+@type: a #GType
+@quark: a #GQuark id to identify the data
+@data: the data
 
 
 <!-- ##### FUNCTION g_type_get_qdata ##### -->
 <para>
-
+Obtains data which has previously been attached to @type
+with g_type_set_qdata().
 </para>
 
-@type: 
-@quark: 
-@Returns: 
+@type: a #GType
+@quark: a #GQuark id to identify the data
+@Returns: the data, or %NULL if no data was found
 
 
 <!-- ##### FUNCTION g_type_query ##### -->
 <para>
+Queries the type system for information about a specific type. 
+This function will fill in a user-provided structure to hold type-specific 
+information. If an invalid #GType is passed in, the @type member of the 
+#GTypeQuery is 0. All members filled into the #GTypeQuery structure should
+be considered constant and have to be left untouched.
 </para>
 
-@type: 
-@query: 
+@type: the #GType value of a static, classed type.
+@query: A user provided structure that is filled in with constant values 
+        upon success.
 
 
 <!-- ##### STRUCT GTypeQuery ##### -->
@@ -1068,20 +1083,27 @@ is used to manage the relationship.
 
 <!-- ##### FUNCTION g_type_add_interface_dynamic ##### -->
 <para>
+Adds the dynamic @interface_type to @instantiable_type. The information
+contained in the #GTypePlugin structure pointed to by @plugin
+is used to manage the relationship.
 </para>
 
-@instance_type: 
-@interface_type: 
-@plugin: 
+@instance_type: the #GType value of an instantiable type.
+@interface_type: the #GType value of an interface type.
+@plugin: the #GTypePlugin structure to retrieve the #GInterfaceInfo from.
 
 
 <!-- ##### FUNCTION g_type_interface_add_prerequisite ##### -->
 <para>
-
+Adds @prerequisite_type to the list of prerequisites of @interface_type.
+This means that any type implementing @interface_type must also implement
+@prerequisite_type. Prerequisites can be thought of as an alternative to
+interface derivation (which GType doesn't support). An interface can have
+at most one instantiatable prerequisite type.
 </para>
 
-@interface_type: 
-@prerequisite_type: 
+@interface_type: #GType value of an interface type.
+@prerequisite_type: #GType value of an interface or instantiatable type.
 
 
 <!-- ##### FUNCTION g_type_get_plugin ##### -->
@@ -1097,11 +1119,16 @@ Returns the #GTypePlugin structure for @type or
 
 <!-- ##### FUNCTION g_type_interface_get_plugin ##### -->
 <para>
+Returns the #GTypePlugin structure for the dynamic interface 
+@interface_type which has been added to @instance_type, or 
+%NULL if @interface_type has not been added to @instance_type or does 
+not have a #GTypePlugin structure. See g_type_add_interface_dynamic().
 </para>
 
-@instance_type: 
-@interface_type: 
-@Returns: 
+@instance_type: the #GType value of an instantiatable type.
+@interface_type: the #GType value of an interface type.
+@Returns: the #GTypePlugin for the dynamic interface @interface_type
+   of @instance_type.
 
 
 <!-- ##### FUNCTION g_type_fundamental_next ##### -->

diff --git a/docs/reference/gobject/tmpl/gtypemodule.sgml b/docs/reference/gobject/tmpl/gtypemodule.sgml
index b098b9d..cdc021e 100644 (file)
--- a/docs/reference/gobject/tmpl/gtypemodule.sgml
+++ b/docs/reference/gobject/tmpl/gtypemodule.sgml
@@ -71,51 +71,70 @@ in #GTypeModuleClass.
 
 <!-- ##### FUNCTION g_type_module_use ##### -->
 <para>
-
+Increases the use count of a #GTypeModule by one. If the
+use count was zero before, the plugin will be loaded.
 </para>
 
-@module: 
-@Returns: 
+@module: a #GTypeModule
+@Returns: %FALSE if the plugin needed to be loaded and
+          loading the plugin failed.
 
 
 <!-- ##### FUNCTION g_type_module_unuse ##### -->
 <para>
-
+Decreases the use count of a #GTypeModule by one. If the
+result is zero, the module will be unloaded. (However, the
+#GTypeModule will not be freed, and types associated with the
+#GTypeModule are not unregistered. Once a #GTypeModule is 
+initialized, it must exist forever.)
 </para>
 
-@module: 
+@module: a #GTypeModule
 
 
 <!-- ##### FUNCTION g_type_module_set_name ##### -->
 <para>
-
+Sets the name for a #GTypeModule 
 </para>
 
-@module: 
-@name: 
+@module: a #GTypeModule.
+@name: a human-readable name to use in error messages.
 
 
 <!-- ##### FUNCTION g_type_module_register_type ##### -->
 <para>
-
+Looks up or registers a type that is implemented with a particular
+type plugin. If a type with name @type_name is already registered,
+the #GType identifier for the type is returned, otherwise the type
+is newly registered, and the resulting #GType identifier returned.
+</para>
+<para>
+As long as any instances of the type exist, the type plugin will
+not be unloaded.
 </para>
 
-@module: 
-@parent_type: 
-@type_name: 
-@type_info: 
-@flags: 
-@Returns: 
+@module:  a #GTypeModule
+@parent_type:    the type for the parent class
+@type_name:      name for the type
+@type_info:      type information structure
+@flags:          flags field providing details about the type
+@Returns: the type ID for the class.
 
 
 <!-- ##### FUNCTION g_type_module_add_interface ##### -->
 <para>
-
+Registers an additional interface for a type, whose interface
+lives in the given type plugin. If the interface was already registered
+for the type in this plugin, nothing will be done. 
+</para>
+<para>
+As long as any instances of the type exist, the type plugin will
+not be unloaded.
 </para>
 
-@module: 
-@instance_type: 
-@interface_type: 
-@interface_info: 
+@module: a #GTypeModule
+@instance_type: type to which to add the interface.
+@interface_type: interface type to add
+@interface_info: type information structure
 
 

diff --git a/docs/reference/gobject/tmpl/objects.sgml b/docs/reference/gobject/tmpl/objects.sgml
index 246d2ab..870d464 100644 (file)
--- a/docs/reference/gobject/tmpl/objects.sgml
+++ b/docs/reference/gobject/tmpl/objects.sgml
@@ -16,8 +16,8 @@ The base object type
 
 <!-- ##### STRUCT GObject ##### -->
 <para>
-All the fields in the GObject structure are private to the #GObject implementation
-and should never be accessed directly.
+All the fields in the <structname>GObject</structname> structure are private 
+to the #GObject implementation and should never be accessed directly.
 </para>
 
 @g_type_instance: 
@@ -37,8 +37,6 @@ and should never be accessed directly.
 @property_id: 
 @value: 
 @pspec: 
-<!-- # Unused Parameters # -->
-@trailer: 
 
 
 <!-- ##### USER_FUNCTION GObjectSetPropertyFunc ##### -->
@@ -50,8 +48,6 @@ and should never be accessed directly.
 @property_id: 
 @value: 
 @pspec: 
-<!-- # Unused Parameters # -->
-@trailer: 
 
 
 <!-- ##### USER_FUNCTION GObjectFinalizeFunc ##### -->
@@ -64,7 +60,7 @@ and should never be accessed directly.
 
 <!-- ##### MACRO G_TYPE_IS_OBJECT ##### -->
 <para>
-Return a boolean value of %FALSE or %TRUE indicating whether
+Returns a boolean value of %FALSE or %TRUE indicating whether
 the passed in type id is a %G_TYPE_OBJECT or derived from it.
 </para>
 
@@ -74,7 +70,7 @@ the passed in type id is a %G_TYPE_OBJECT or derived from it.
 
 <!-- ##### MACRO G_OBJECT ##### -->
 <para>
-Cast a #GObject or derived pointer into a (GObject*) pointer.
+Casts a #GObject or derived pointer into a (GObject*) pointer.
 Depending on the current debugging level, this function may invoke
 certain runtime checks to identify invalid casts.
 </para>
@@ -84,7 +80,7 @@ certain runtime checks to identify invalid casts.
 
 <!-- ##### MACRO G_IS_OBJECT ##### -->
 <para>
-Check whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
+Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
 </para>
 
 @object: Instance to check for being a %G_TYPE_OBJECT.
@@ -92,26 +88,27 @@ Check whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
 
 <!-- ##### MACRO G_OBJECT_CLASS ##### -->
 <para>
-
+Casts a derived #GObjectClass structure into a #GObjectClass structure.
 </para>
 
-@class: 
+@class: a valid #GObjectClass
 
 
 <!-- ##### MACRO G_IS_OBJECT_CLASS ##### -->
 <para>
-
+Checks whether @class "is a" valid #GObjectClass structure of type
+%G_TYPE_OBJECT or derived.
 </para>
 
-@class: 
+@class: a #GObjectClass
 
 
 <!-- ##### MACRO G_OBJECT_GET_CLASS ##### -->
 <para>
-
+Returns the class structure associated to a #GObject instance.
 </para>
 
-@object: 
+@object: a #GObject instance.
 
 
 <!-- ##### MACRO G_OBJECT_TYPE ##### -->
@@ -125,10 +122,12 @@ Return the type id of an object.
 
 <!-- ##### MACRO G_OBJECT_TYPE_NAME ##### -->
 <para>
-
+Returns the name of an object's type.
 </para>
 
-@object: 
+@object: Object to return the type name for.
+@Returns: Type name of @object. The string is owned by the type system and 
+should not be freed.
 
 
 <!-- ##### MACRO G_OBJECT_CLASS_TYPE ##### -->
@@ -149,10 +148,14 @@ Return the type id of an object.
 
 <!-- ##### FUNCTION g_object_class_install_property ##### -->
 <para>
-
+Installs a new property. This is usually done in the class initializer.
 </para>
 
 @oclass: 
+@property_id: the id for the new property
+@pspec: the #GParamSpec for the new property
+<!-- # Unused Parameters # -->
+@class: a #GObjectClass
 @property_id: 
 @pspec: 
 
@@ -325,27 +328,29 @@ to match the one used with g_object_add_weak_pointer().
 
 <!-- ##### FUNCTION g_object_notify ##### -->
 <para>
-
+Emits a "notify" signal for the property @property_name on @object. 
 </para>
 
-@object: 
-@property_name: 
+@object: a #GObject
+@property_name: the name of a property installed on the class of @object.
 
 
 <!-- ##### FUNCTION g_object_freeze_notify ##### -->
 <para>
-
+Stops emission of "notify" signals on @object. The signals are
+queued until g_object_thaw_notify() is called on @object. 
 </para>
 
-@object: 
+@object: a #GObject
 
 
 <!-- ##### FUNCTION g_object_thaw_notify ##### -->
 <para>
-
+Reverts the effect of a previous call to g_object_freeze_notify().
+This causes all queued "notify" signals on @object to be emitted.
 </para>
 
-@object: 
+@object: a #GObject
 
 
 <!-- ##### FUNCTION g_object_get_data ##### -->

diff --git a/docs/reference/gobject/tmpl/param_value_types.sgml b/docs/reference/gobject/tmpl/param_value_types.sgml
index b8fb0dc..3cbb303 100644 (file)
--- a/docs/reference/gobject/tmpl/param_value_types.sgml
+++ b/docs/reference/gobject/tmpl/param_value_types.sgml
@@ -60,14 +60,19 @@ A #GParamSpec derived structure that contains the meta data for boolean properti
 
 <!-- ##### 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 ##### -->
@@ -131,16 +136,17 @@ A #GParamSpec derived structure that contains the meta data for character proper
 
 <!-- ##### 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 ##### -->
@@ -204,16 +210,17 @@ A #GParamSpec derived structure that contains the meta data for unsigned charact
 
 <!-- ##### 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 ##### -->
@@ -277,16 +284,20 @@ A #GParamSpec derived structure that contains the meta data for integer properti
 
 <!-- ##### 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 ##### -->
@@ -350,16 +361,20 @@ A #GParamSpec derived structure that contains the meta data for unsigned integer
 
 <!-- ##### 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 ##### -->
@@ -423,16 +438,20 @@ A #GParamSpec derived structure that contains the meta data for long integer pro
 
 <!-- ##### 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 ##### -->
@@ -496,17 +515,20 @@ A #GParamSpec derived structure that contains the meta data for unsigned long in
 
 <!-- ##### 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 ##### -->
@@ -570,16 +592,20 @@ A #GParamSpec derived structure that contains the meta data for 64bit integer pr
 
 <!-- ##### 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 ##### -->
@@ -643,16 +669,21 @@ A #GParamSpec derived structure that contains the meta data for unsigned 64bit i
 
 <!-- ##### 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 ##### -->
@@ -717,16 +748,20 @@ A #GParamSpec derived structure that contains the meta data for float properties
 
 <!-- ##### 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 ##### -->
@@ -791,16 +826,21 @@ A #GParamSpec derived structure that contains the meta data for double propertie
 
 <!-- ##### 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 ##### -->
@@ -1200,14 +1240,19 @@ A #GParamSpec derived structure that contains the meta data for boxed properties
 
 <!-- ##### 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 ##### -->
@@ -1447,14 +1492,20 @@ A #GParamSpec derived structure that contains the meta data for unichar (unsigne
 
 <!-- ##### 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 ##### -->
@@ -1491,13 +1542,21 @@ A #GParamSpec derived structure that contains the meta data for #GValueArray pro
 
 <!-- ##### 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 
 
 

diff --git a/docs/reference/gobject/tmpl/signals.sgml b/docs/reference/gobject/tmpl/signals.sgml
index cc6dc6c..7ede610 100644 (file)
--- a/docs/reference/gobject/tmpl/signals.sgml
+++ b/docs/reference/gobject/tmpl/signals.sgml
@@ -233,135 +233,213 @@ of g_signal_new().
 
 <!-- ##### 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 ##### -->
@@ -412,15 +490,22 @@ calling the handler.
 
 <!-- ##### 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 ##### -->
@@ -436,131 +521,194 @@ connection.
 
 <!-- ##### 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 ##### -->
@@ -598,97 +746,126 @@ Disconnects all handlers on an instance that match @func and @data.
 
 <!-- ##### 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 ##### -->