g_object_get_property: document that value must be initialized

I couldn't tell from reading the documentation whether I had to pass in
an uninitialized value, or a value initialized to the exact type, or
something else. It turns out (from reading the source) that you have to
pass in an initialized value, but you can use any type to which the
property's actual type can be transformed.

So, let's document this.

diff --git a/gobject/gobject.c b/gobject/gobject.c
index 8b427fa..f1fa54d 100644 (file)
--- a/gobject/gobject.c
+++ b/gobject/gobject.c
@@ -1906,7 +1906,9 @@ g_object_set_property (GObject        *object,
  * @property_name: the name of the property to get
  * @value: return location for the property value
  *
- * Gets a property of an object.
+ * Gets a property of an object. @value must have been initialized to the
+ * expected type of the property (or a type to which the expected type can be
+ * transformed) using g_value_init().
  *
  * In general, a copy is made of the property contents and the caller is
  * responsible for freeing the memory by calling g_value_unset().