Improve g_value_set_object docs

svn path=/trunk/; revision=5784

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index a372215c1082dca2005a91b12f29ad96a5bafbf3..8d36d23f32b1d9f2af7fe4e133bbfaa0bac7fe8a 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,9 @@
+2007-10-16  Matthias Clasen  <mclasen@redhat.com>
+
+       * gobject/tmpl/param_value_types.sgml: Add some discussion on 
+       g_value_set_object() vs g_value_take_object().  (#477957, Davyd
+       Madeley)
+
 2007-09-19  Behdad Esfahbod  <behdad@gnome.org>
 
        * glib/building.sgml: Fix gettext URL. (#478349, kraai ftbfs.org)

diff --git a/docs/reference/gobject/tmpl/param_value_types.sgml b/docs/reference/gobject/tmpl/param_value_types.sgml
index 06850aae07c75f339e26aa77ec74490398d050ee..242b79f363023aadeada919d275075f9d8b8f8fb 100644 (file)
--- a/docs/reference/gobject/tmpl/param_value_types.sgml
+++ b/docs/reference/gobject/tmpl/param_value_types.sgml
@@ -1504,6 +1504,19 @@ See g_param_spec_internal() for details on property names.
 <para>
 Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object.
 </para>
+<para>
+g_value_set_object() increases the reference count of @v_object
+(the #GValue holds a reference to @v_object).
+If you do not wish to increase the reference count of the object
+(i.e. you wish to pass your current reference to the #GValue because you no
+longer need it),
+use g_value_take_object() instead.
+</para>
+<para>
+It is important that your #GValue holds a reference to @v_object (either its
+own, or one it has taken) to ensure that the object won't be destroyed while
+the #GValue still exists).
+</para>
 
 @value:   a valid #GValue of %G_TYPE_OBJECT derived type
 @v_object: object value to be set
@@ -1513,7 +1526,12 @@ Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object.
 <para>
 Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object 
 and takes over the ownership of the callers reference to @v_object; 
-the caller doesn't have to unref it any more.
+the caller doesn't have to unref it any more (i.e. the reference
+count of the object is not increased).
+</para>
+<para>
+If you want the #GValue to hold its own reference to @v_object, use
+g_value_set_object() instead.
 </para>
 
 @value:  a valid #GValue of %G_TYPE_OBJECT derived type