Additions.

Sun Oct 19 00:33:28 2003  Matthias Clasen  <maclas@gmx.de>

	* gobject/tmpl/gtype.sgml:
	* gobject/tmpl/generic_values.sgml:
	* gobject/tmpl/objects.sgml:
	* gobject/tmpl/signals.sgml: Additions.

docs/reference/ChangeLog

@@ -1,3 +1,10 @@
+Sun Oct 19 00:33:28 2003  Matthias Clasen  <maclas@gmx.de>
+
+	* gobject/tmpl/gtype.sgml: 
+	* gobject/tmpl/generic_values.sgml: 
+	* gobject/tmpl/objects.sgml: 
+	* gobject/tmpl/signals.sgml: Additions.
+
 Sat Oct 18 01:30:47 2003  Matthias Clasen  <maclas@gmx.de>
 
 	* gobject/tmpl/gboxed.sgml: 

docs/reference/gobject/tmpl/generic_values.sgml

@@ -213,21 +213,25 @@ as rcfile value or object property serialization).
 
 <!-- ##### USER_FUNCTION GValueTransform ##### -->
 <para>
-
+The type of value transformation functions which can be registered with
+g_value_register_transform_func().
 </para>
 
-@src_value: 
+@src_value:  Source value.
-@dest_value: 
+@dest_value: Target value.
 
 
 <!-- ##### FUNCTION g_value_register_transform_func ##### -->
 <para>
-
+Registers a value transformation function for use in g_value_transform().
+A previously registered transformation function for @src_type and @dest_type
+will be replaced.
 </para>
 
-@src_type: 
+@src_type:  Source type.
-@dest_type: 
+@dest_type: Target type.
-@transform_func: 
+@transform_func: a function which transforms values of type @src_type
+  into value of type @dest_type
 
 
 <!-- ##### FUNCTION g_strdup_value_contents ##### -->

docs/reference/gobject/tmpl/gtype.sgml

@@ -546,11 +546,10 @@ class_init function with g_type_class_add_private().
 
 <!-- ##### MACRO G_TYPE_FLAG_RESERVED_ID_BIT ##### -->
 <para>
-
+A bit in the type number that's supposed to be left untouched.
 </para>
 
 
-
 <!-- ##### FUNCTION g_type_init ##### -->
 <para>
 Prior to any use of the type system, g_type_init() has to be called to initialize
@@ -802,16 +801,18 @@ have been installed.
  g_type_default_interface_unref() when you are done using
  the interface.
 
+
 <!-- ##### FUNCTION g_type_default_interface_peek ##### -->
 <para>
 If the interface type @g_type is currently in use, returns
 its default interface vtable.    
 </para>
 
-@g_type: an interface type 
+@g_type: an interface type
 @Returns: the default vtable for the interface; or %NULL
  if the type is not currently in use.
 
+
 <!-- ##### FUNCTION g_type_default_interface_unref ##### -->
 <para>
 Decrements the reference count for the type corresponding to the
@@ -825,6 +826,7 @@ vtable (the <structfield>class_finalize</structfield> member of
 @g_iface: the default vtable structure for a interface, as
   returned by g_type_default_interface_ref()
 
+
 <!-- ##### FUNCTION g_type_children ##### -->
 <para>
 Return a newly allocated and 0-terminated array of type IDs, listing the
@@ -1093,12 +1095,22 @@ allocated by the corresponding GInterfaceInitFunc() function.
 
 <!-- ##### USER_FUNCTION GTypeClassCacheFunc ##### -->
 <para>
-
+A callback function which is called when the reference count of a class 
+drops to zero. It may use g_type_class_ref() to prevent the class from
+being freed. You should not call g_type_class_unref() from a 
+#GTypeClassCacheFunc function to prevent infinite recursion, use 
+g_type_class_unref_uncached() instead.
+</para>
+<para>
+The functions have to check the class id passed in to figure 
+whether they actually want to cache the class of this type, since all
+classes are routed through the same #GTypeClassCacheFunc chain.
 </para>
 
-@cache_data: 
+@cache_data: data that was given to the g_type_add_class_cache_func() call
-@g_class: 
+@g_class: The #GTypeClass structure which is unreferenced
-@Returns: 
+@Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being 
+called, %FALSE to continue.
 
 
 <!-- ##### ENUM GTypeFlags ##### -->
@@ -1286,9 +1298,7 @@ Frees an instance of a type, returning it to the instance pool for the type,
 if there is one.
 </para>
 <para>
-Like g_type_create_i	* gobject/tmpl/gtype.sgml: 
+Like g_type_create_instance(), this function is reserved for implementors of 
-	* gobject/tmpl/enumerations_flags.sgml: Add docs.
-nstance(), this function is reserved for implementors of 
 fundamental types.
 </para>
 
@@ -1297,28 +1307,38 @@ fundamental types.
 
 <!-- ##### FUNCTION g_type_add_class_cache_func ##### -->
 <para>
-
+Adds a #GTypeClassCacheFunc to be called before the reference count of a class 
+goes from one to zero. This can be used to prevent premature class destruction.
+All installed #GTypeClassCacheFunc functions will be chained until one of them 
+returns %TRUE. The functions have to check the class id passed in to figure 
+whether they actually want to cache the class of this type, since all classes
+are routed through the same #GTypeClassCacheFunc chain.
 </para>
 
-@cache_data: 
+@cache_data: data to be passed to @cache_func
-@cache_func: 
+@cache_func: a #GTypeClassCacheFunc
 
 
 <!-- ##### FUNCTION g_type_remove_class_cache_func ##### -->
 <para>
-
+Removes a previously installed #GTypeClassCacheFunc. The cache maintained 
+by @cache_func has to be empty when calling g_type_remove_class_cache_func() 
+to avoid leaks.
 </para>
 
-@cache_data: 
+@cache_data: data that was given when adding @cache_func
-@cache_func: 
+@cache_func: a #GTypeClassCacheFunc 
 
 
 <!-- ##### FUNCTION g_type_class_unref_uncached ##### -->
 <para>
-
+A variant of g_type_class_unref() for use in #GTypeClassCacheFunc
+implementations. It unreferences a class without consulting the chain
+of #GTypeClassCacheFunc<!-- -->s, avoiding the recursion which would occur
+otherwise.
 </para>
 
-@g_class: 
+@g_class: The #GTypeClass structure to unreference.
 
 
 <!-- ##### FUNCTION g_type_add_interface_check ##### -->
@@ -1521,38 +1541,40 @@ The fundamental type for #GObject.
 </para>
 
 
-
 <!-- ##### MACRO G_TYPE_RESERVED_GLIB_FIRST ##### -->
 <para>
-
+First fundamental type number to create a new fundamental type id with
+G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib.
 </para>
 
 
 
 <!-- ##### MACRO G_TYPE_RESERVED_GLIB_LAST ##### -->
 <para>
-
+Last fundamental type number reserved for GLib.
 </para>
 
 
 
 <!-- ##### MACRO G_TYPE_RESERVED_BSE_FIRST ##### -->
 <para>
-
+First fundamental type number to create a new fundamental type id with
+G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE.
 </para>
 
 
 
 <!-- ##### MACRO G_TYPE_RESERVED_BSE_LAST ##### -->
 <para>
-
+Last fundamental type number reserved for BSE.
 </para>
 
 
 
 <!-- ##### MACRO G_TYPE_RESERVED_USER_FIRST ##### -->
 <para>
-
+First available fundamental type number to create new fundamental 
+type id with G_TYPE_MAKE_FUNDAMENTAL().
 </para>
 
 <!--

docs/reference/gobject/tmpl/objects.sgml

@@ -20,7 +20,17 @@ 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: 
+
+<!-- ##### SIGNAL GObject::notify ##### -->
+<para>
+The notify signal is emitted on an object when one of its properties 
+has been changed. Note that getting this signal doesn't guarantee that the
+value of the property has actually changed, it may also be emitted when
+the setter for the property is called to reinstate the previous value.
+</para>
+
+@gobject: the object which received the signal.
+@pspec: the #GParamSpec of the property which changed
 
 <!-- ##### STRUCT GObjectClass ##### -->
 <para>
@@ -31,32 +41,34 @@ to the #GObject implementation and should never be accessed directly.
 
 <!-- ##### USER_FUNCTION GObjectGetPropertyFunc ##### -->
 <para>
-
+The type of the @get_property function of #GObjectClass. 
 </para>
 
-@object: 
+@object: a #GObject
-@property_id: 
+@property_id: the numeric id under which the property was registered with
-@value: 
+   g_object_class_install_property().
-@pspec: 
+@value: a #GValue to return the property value in
+@pspec: the #GParamSpec describing the property
 
 
 <!-- ##### USER_FUNCTION GObjectSetPropertyFunc ##### -->
 <para>
-
+The type of the @set_property function of #GObjectClass. 
 </para>
 
-@object: 
+@object: a #GObject
-@property_id: 
+@property_id: the numeric id under which the property was registered with
-@value: 
+   g_object_class_install_property().
-@pspec: 
+@value: the new value for the property
+@pspec: the #GParamSpec describing the property
 
 
 <!-- ##### USER_FUNCTION GObjectFinalizeFunc ##### -->
 <para>
-
+The type of the @finalize function of #GObjectClass.
 </para>
 
-@object: 
+@object: the #GObject being finalized
 
 
 <!-- ##### MACRO G_TYPE_IS_OBJECT ##### -->
@@ -241,11 +253,14 @@ When its reference count drops to 0, the object is finalized (i.e. its memory is
 
 <!-- ##### USER_FUNCTION GWeakNotify ##### -->
 <para>
-
+A #GWeakNotify function can be added to an object as a callback that gets
+triggered when the object is finalized. Since the object is already being
+finalized when the #GWeakNotify is called, there's not much you could do 
+with the object, apart from e.g. using its adress as hash-index or the like. 
 </para>
 
-@data: 
+@data: data that was provided when the weak reference was established
-@where_the_object_was: 
+@where_the_object_was: the object being finalized
 
 
 <!-- ##### FUNCTION g_object_weak_ref ##### -->
@@ -687,8 +702,8 @@ See g_object_get().
 This function essentially limits the life time of the @closure
 to the life time of the object. That is, when the object is finalized,
 the @closure is invalidated by calling g_closure_invalidate() on it,
-in order to prevent invocations of the closure with a finalized (non
+in order to prevent invocations of the closure with a finalized 
-existing) object. Also, g_object_ref() and g_object_unref() are added
+(nonexisting) object. Also, g_object_ref() and g_object_unref() are added
 as marshal guards to the @closure, to ensure that an extra reference
 count is held on @object during invocation of the @closure.
 Usually, this function will be called on closures that use this @object

docs/reference/gobject/tmpl/signals.sgml

@@ -862,12 +862,15 @@ Returns the invocation hint of the innermost signal emission of instance.
 
 <!-- ##### FUNCTION g_signal_type_cclosure_new ##### -->
 <para>
-
+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.
 </para>
 
-@itype: 
+@itype: the #GType identifier of an interface or classed type
-@struct_offset: 
+@struct_offset: the offset of the member function of @itype's class 
-@Returns: 
+  structure which is to be invoked by the new closure
+@Returns: a new #GCClosure
 
 
 <!-- ##### FUNCTION g_signal_accumulator_true_handled ##### -->