doc common functions like ref/ sink/unref/invalidate.

Mon Feb  4 17:55:39 2002  Tim Janik  <timj@gtk.org>

        * gobject/tmpl/closures.sgml: doc common functions like ref/
        sink/unref/invalidate.

3 files changed, 59 insertions, 26 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 3d603f7f6..8e04a1b96 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,6 +1,9 @@
 Mon Feb  4 17:55:39 2002  Tim Janik  <timj@gtk.org>
+	
+	* gobject/tmpl/closures.sgml: doc common functions like ref/
+	sink/unref/invalidate.
 
-	* gobject/tmpl/objects.sgml: document g_obejct_watch_closure() and
+	* gobject/tmpl/objects.sgml: document g_object_watch_closure() and
 	qdata functions.
 
 Tue Jan 29 12:00:59 2002  Owen Taylor  <otaylor@redhat.com>
diff --git a/docs/reference/gobject/tmpl/gclosure.sgml b/docs/reference/gobject/tmpl/gclosure.sgml
index 54f773374..5c26553a3 100644
--- a/docs/reference/gobject/tmpl/gclosure.sgml
+++ b/docs/reference/gobject/tmpl/gclosure.sgml
@@ -58,7 +58,7 @@ Closures
 
 </para>
 
-@is_invalid: 
+@is_invalid: Indicates whether the closure has been invalidated by g_closure_invalidate()
 
 <!-- ##### MACRO G_TYPE_CLOSURE ##### -->
 <para>
@@ -159,27 +159,54 @@ Closures
 
 <!-- ##### FUNCTION g_closure_ref ##### -->
 <para>
-
+Increment the reference count on a closure to force it staying
+alive while the caller holds a pointer to it.
 </para>
 
-@closure: 
-@Returns: 
+@closure: #GClosure to increment the reference count on
+@Returns: The @closure passed in, for convenience
 
 
 <!-- ##### FUNCTION g_closure_sink ##### -->
 <para>
-
-</para>
-
-@closure: 
+Take over the initial ownership of a closure.
+When closures are newly created, they get an initial reference count
+of 1, eventhough no caller has yet invoked g_closure_ref() on the @closure.
+Code entities that store closures for notification purposes are supposed
+to call this function, for example like this:
+<msgtext><programlisting>
+static GClosure *notify_closure = NULL;
+void
+foo_notify_set_closure (GClosure *closure)
+{
+  if (notify_closure)
+    g_closure_unref (notify_closure);
+  notify_closure = closure;
+  if (notify_closure)
+    {
+      g_closure_ref (notify_closure);
+      g_closure_sink (notify_closure);
+    }
+}
+</programlisting></msgtext>
+Because g_closure_sink() may decrement the reference count of a closure
+(if it hasn't been called on @closure yet) just like g_closure_unref(),
+g_closure_ref() should be called prior to this function.
+</para>
+
+@closure: #GClosure to decrement the initial reference count on, if it's
+          still being held
 
 
 <!-- ##### FUNCTION g_closure_unref ##### -->
 <para>
-
+Decrement the reference count of a closure after it was
+previously incremented by the same caller. The closure
+will most likely be destroyed and freed after this function
+returns.
 </para>
 
-@closure: 
+@closure: #GClosure to decrement the reference count on
 
 
 <!-- ##### FUNCTION g_closure_invoke ##### -->
@@ -196,10 +223,12 @@ Closures
 
 <!-- ##### FUNCTION g_closure_invalidate ##### -->
 <para>
-
+This function sets a flag on the closure to indicate that it's
+calling environment has become invalid, and thus causes any future
+invocations of g_closure_invoke() on this @closure to be ignored.
 </para>
 
-@closure: 
+@closure: GClosure to invalidate
 
 
 <!-- ##### FUNCTION g_closure_add_finalize_notifier ##### -->
diff --git a/docs/reference/gobject/tmpl/objects.sgml b/docs/reference/gobject/tmpl/objects.sgml
index c1f0a2f3b..73e11c4fa 100644
--- a/docs/reference/gobject/tmpl/objects.sgml
+++ b/docs/reference/gobject/tmpl/objects.sgml
@@ -389,6 +389,17 @@ to match the one used with g_object_add_weak_pointer().
 @Returns: 
 
 
+<!-- ##### FUNCTION g_object_get_qdata ##### -->
+<para>
+This function gets back user data pointers stored via
+g_object_set_qdata().
+</para>
+
+@object:  The GObject to get a stored user data pointer from
+@quark:   A #GQuark, naming the user data pointer
+@Returns: The user data pointer set, or %NULL
+
+
 <!-- ##### FUNCTION g_object_set_qdata ##### -->
 <para>
 This sets an opaque, named pointer on an object.
@@ -406,17 +417,6 @@ removes the data stored.
 @data:   An opaque user data pointer
 
 
-<!-- ##### FUNCTION g_object_get_qdata ##### -->
-<para>
-This function gets back user data pointers stored via
-g_object_set_qdata().
-</para>
-
-@object:  The GObject to get a stored user data pointer from
-@quark:   A #GQuark, naming the user data pointer
-@Returns: The user data pointer set, or %NULL
-
-
 <!-- ##### FUNCTION g_object_set_qdata_full ##### -->
 <para>
 This function works like g_object_set_qdata(), but in addition,
@@ -465,7 +465,7 @@ free_string_list (gpointer data)
   g_list_free (list);
 }
 </programlisting></msgtext>
-Using g_object_get_qdata() in teh above example, instead of g_object_steal_qdata()
+Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata()
 would have left the destroy function set, and thus the partial string list would
 have been freed upon g_object_set_qdata_full().
 </para>
@@ -540,7 +540,8 @@ as closure data.
 </para>
 
 @object:  GObject restricting lifetime of @closure
-@closure: GClosure to watch 
+@closure: GClosure to watch
+
 
 <!-- ##### FUNCTION g_object_run_dispose ##### -->
 <para>