[glib] Add GI annotations to GObject

[Pavel Holejsovsky <pholejs src gnome org>]

commit 58e36daf29aa1cf042a1141b9bbb91b4e794bfc7
Author: Pavel Holejsovsky <pholejs src gnome org>
Date:   Mon Dec 27 22:07:08 2010 +0100

    Add GI annotations to GObject

 gobject/gobject.c |  100 +++++++++++++++++++++++++++-------------------------
 1 files changed, 52 insertions(+), 48 deletions(-)
---
diff --git a/gobject/gobject.c b/gobject/gobject.c
index 5587df9..201f9f7 100644
--- a/gobject/gobject.c
+++ b/gobject/gobject.c
@@ -617,8 +617,8 @@ g_object_interface_install_property (gpointer      g_iface,
  *
  * Looks up the #GParamSpec for a property of a class.
  *
- * Returns: the #GParamSpec for the property, or %NULL if the class
- *          doesn't have a property of that name
+ * Returns: (transfer none): the #GParamSpec for the property, or
+ *          %NULL if the class doesn't have a property of that name
  */
 GParamSpec*
 g_object_class_find_property (GObjectClass *class,
@@ -660,8 +660,9 @@ g_object_class_find_property (GObjectClass *class,
  *
  * Since: 2.4
  *
- * Returns: the #GParamSpec for the property of the interface with the
- *          name @property_name, or %NULL if no such property exists.
+ * Returns: (transfer none): the #GParamSpec for the property of the
+ *          interface with the name @property_name, or %NULL if no
+ *          such property exists.
  */
 GParamSpec*
 g_object_interface_find_property (gpointer      g_iface,
@@ -760,11 +761,11 @@ g_object_class_override_property (GObjectClass *oclass,
 /**
  * g_object_class_list_properties:
  * @oclass: a #GObjectClass
- * @n_properties: return location for the length of the returned array
+ * @n_properties: (out): return location for the length of the returned array
  *
  * Get an array of #GParamSpec* for all properties of a class.
  *
- * Returns: (array length=n_properties) (transfer full): an array of
+ * Returns: (array length=n_properties) (transfer container): an array of
  *          #GParamSpec* which should be freed after use
  */
 GParamSpec** /* free result */
@@ -789,7 +790,7 @@ g_object_class_list_properties (GObjectClass *class,
  * g_object_interface_list_properties:
  * @g_iface: any interface vtable for the interface, or the default
  *  vtable for the interface
- * @n_properties_p: location to store number of properties returned.
+ * @n_properties_p: (out): location to store number of properties returned.
  *
  * Lists the properties of an interface.Generally, the interface
  * vtable passed in as @g_iface will be the default vtable from
@@ -798,7 +799,8 @@ g_object_class_list_properties (GObjectClass *class,
  *
  * Since: 2.4
  *
- * Returns: a pointer to an array of pointers to #GParamSpec
+ * Returns: (array length=n_properties_p) (transfer container): a
+ *          pointer to an array of pointers to #GParamSpec
  *          structures. The paramspecs are owned by GLib, but the
  *          array should be freed with g_free() when you are done with
  *          it.
@@ -1270,7 +1272,7 @@ g_object_get_type (void)
 }
 
 /**
- * g_object_new:
+ * g_object_new: (skip)
  * @object_type: the type id of the #GObject subtype to instantiate
  * @first_property_name: the name of the first property
  * @...: the value of the first property, followed optionally by more
@@ -1281,7 +1283,7 @@ g_object_get_type (void)
  * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
  * which are not explicitly specified are set to their default values.
  *
- * Returns: a new instance of @object_type
+ * Returns: (transfer full): a new instance of @object_type
  */
 gpointer
 g_object_new (GType	   object_type,
@@ -1340,14 +1342,16 @@ object_in_construction_list (GObject *object)
  * g_object_newv:
  * @object_type: the type id of the #GObject subtype to instantiate
  * @n_parameters: the length of the @parameters array
- * @parameters: an array of #GParameter
+ * @parameters: (array length=n_parameters): an array of #GParameter
  *
  * Creates a new instance of a #GObject subtype and sets its properties.
  *
  * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
  * which are not explicitly specified are set to their default values.
  *
- * Returns: a new instance of @object_type
+ * Rename to: g_object_new
+ * Returns: (type GObject.Object) (transfer full): a new instance of
+ * @object_type
  */
 gpointer
 g_object_newv (GType       object_type,
@@ -1513,7 +1517,7 @@ g_object_newv (GType       object_type,
 }
 
 /**
- * g_object_new_valist:
+ * g_object_new_valist: (skip)
  * @object_type: the type id of the #GObject subtype to instantiate
  * @first_property_name: the name of the first property
  * @var_args: the value of the first property, followed optionally by more
@@ -1627,7 +1631,7 @@ g_object_constructor (GType                  type,
 }
 
 /**
- * g_object_set_valist:
+ * g_object_set_valist: (skip)
  * @object: a #GObject
  * @first_property_name: name of the first property to set
  * @var_args: value for the first property, followed optionally by more
@@ -1703,7 +1707,7 @@ g_object_set_valist (GObject	 *object,
 }
 
 /**
- * g_object_get_valist:
+ * g_object_get_valist: (skip)
  * @object: a #GObject
  * @first_property_name: name of the first property to get
  * @var_args: return location for the first property, followed optionally by more
@@ -1779,7 +1783,7 @@ g_object_get_valist (GObject	 *object,
 }
 
 /**
- * g_object_set:
+ * g_object_set: (skip)
  * @object: a #GObject
  * @first_property_name: name of the first property to set
  * @...: value for the first property, followed optionally by more
@@ -1803,7 +1807,7 @@ g_object_set (gpointer     _object,
 }
 
 /**
- * g_object_get:
+ * g_object_get: (skip)
  * @object: a #GObject
  * @first_property_name: name of the first property to get
  * @...: return location for the first property, followed optionally by more
@@ -1980,7 +1984,7 @@ g_object_get_property (GObject	   *object,
 }
 
 /**
- * g_object_connect:
+ * g_object_connect: (skip)
  * @object: a #GObject
  * @signal_spec: the spec for the first signal
  * @...: #GCallback for the first signal, followed by data for the
@@ -2060,7 +2064,7 @@ g_object_get_property (GObject	   *object,
  * 				     NULL);
  * ]|
  *
- * Returns: @object
+ * Returns: (transfer none): @object
  */
 gpointer
 g_object_connect (gpointer     _object,
@@ -2132,7 +2136,7 @@ g_object_connect (gpointer     _object,
 }
 
 /**
- * g_object_disconnect:
+ * g_object_disconnect: (skip)
  * @object: a #GObject
  * @signal_spec: the spec for the first signal
  * @...: #GCallback for the first signal, followed by data for the first signal,
@@ -2215,7 +2219,7 @@ weak_refs_notify (gpointer data)
 }
 
 /**
- * g_object_weak_ref:
+ * g_object_weak_ref: (skip)
  * @object: #GObject to reference weakly
  * @notify: callback to invoke before the object is freed
  * @data: extra data to pass to notify
@@ -2259,7 +2263,7 @@ g_object_weak_ref (GObject    *object,
 }
 
 /**
- * g_object_weak_unref:
+ * g_object_weak_unref: (skip)
  * @object: #GObject to remove a weak reference from
  * @notify: callback to search for
  * @data: data to search for
@@ -2301,7 +2305,7 @@ g_object_weak_unref (GObject    *object,
 }
 
 /**
- * g_object_add_weak_pointer:
+ * g_object_add_weak_pointer: (skip)
  * @object: The object that should be weak referenced.
  * @weak_pointer_location: (inout): The memory address of a pointer.
  *
@@ -2323,7 +2327,7 @@ g_object_add_weak_pointer (GObject  *object,
 }
 
 /**
- * g_object_remove_weak_pointer:
+ * g_object_remove_weak_pointer: (skip)
  * @object: The object that is weak referenced.
  * @weak_pointer_location: (inout): The memory address of a pointer.
  *
@@ -2369,7 +2373,7 @@ object_floating_flag_handler (GObject        *object,
 
 /**
  * g_object_is_floating:
- * @object: a #GObject
+ * @object: (type GObject.Object): a #GObject
  *
  * Checks wether @object has a <link linkend="floating-ref">floating</link>
  * reference.
@@ -2388,7 +2392,7 @@ g_object_is_floating (gpointer _object)
 
 /**
  * g_object_ref_sink:
- * @object: a #GObject
+ * @object: (type GObject.Object): a #GObject
  *
  * Increase the reference count of @object, and possibly remove the
  * <link linkend="floating-ref">floating</link> reference, if @object
@@ -2402,7 +2406,7 @@ g_object_is_floating (gpointer _object)
  *
  * Since: 2.10
  *
- * Returns: @object
+ * Returns: (type GObject.Object) (transfer none): @object
  */
 gpointer
 g_object_ref_sink (gpointer _object)
@@ -2468,7 +2472,7 @@ toggle_refs_notify (GObject *object,
 }
 
 /**
- * g_object_add_toggle_ref:
+ * g_object_add_toggle_ref: (skip)
  * @object: a #GObject
  * @notify: a function to call when this reference is the
  *  last reference to the object, or is no longer
@@ -2549,7 +2553,7 @@ g_object_add_toggle_ref (GObject       *object,
 }
 
 /**
- * g_object_remove_toggle_ref:
+ * g_object_remove_toggle_ref: (skip)
  * @object: a #GObject
  * @notify: a function to call when this reference is the
  *  last reference to the object, or is no longer
@@ -2603,11 +2607,11 @@ g_object_remove_toggle_ref (GObject       *object,
 
 /**
  * g_object_ref:
- * @object: a #GObject
+ * @object: (type GObject.Object): a #GObject
  *
  * Increases the reference count of @object.
  *
- * Returns: the same @object
+ * Returns: (type GObject.Object) (transfer none): the same @object
  */
 gpointer
 g_object_ref (gpointer _object)
@@ -2636,7 +2640,7 @@ g_object_ref (gpointer _object)
 
 /**
  * g_object_unref:
- * @object: a #GObject
+ * @object: (type GObject.Object): a #GObject
  *
  * Decreases the reference count of @object. When its reference count
  * drops to 0, the object is finalized (i.e. its memory is freed).
@@ -2732,7 +2736,7 @@ g_object_unref (gpointer _object)
 }
 
 /**
- * g_clear_object:
+ * g_clear_object: (skip)
  * @object_ptr: a pointer to a #GObject reference
  *
  * Clears a reference to a #GObject.
@@ -2777,7 +2781,7 @@ g_clear_object (volatile GObject **object_ptr)
  * This function gets back user data pointers stored via
  * g_object_set_qdata().
  * 
- * Returns: The user data pointer set, or %NULL
+ * Returns: (transfer none): The user data pointer set, or %NULL
  */
 gpointer
 g_object_get_qdata (GObject *object,
@@ -2789,7 +2793,7 @@ g_object_get_qdata (GObject *object,
 }
 
 /**
- * g_object_set_qdata:
+ * g_object_set_qdata: (skip)
  * @object: The GObject to set store a user data pointer
  * @quark: A #GQuark, naming the user data pointer
  * @data: An opaque user data pointer
@@ -2815,7 +2819,7 @@ g_object_set_qdata (GObject *object,
 }
 
 /**
- * g_object_set_qdata_full:
+ * g_object_set_qdata_full: (skip)
  * @object: The GObject to set store a user data pointer
  * @quark: A #GQuark, naming the user data pointer
  * @data: An opaque user data pointer
@@ -2882,7 +2886,7 @@ g_object_set_qdata_full (GObject       *object,
  * and thus the partial string list would have been freed upon
  * g_object_set_qdata_full().
  *
- * Returns: The user data pointer set, or %NULL
+ * Returns: (transfer full): The user data pointer set, or %NULL
  */
 gpointer
 g_object_steal_qdata (GObject *object,
@@ -2901,7 +2905,7 @@ g_object_steal_qdata (GObject *object,
  * 
  * Gets a named field from the objects table of associations (see g_object_set_data()).
  * 
- * Returns: the data if found, or %NULL if no such data exists.
+ * Returns: (transfer none): the data if found, or %NULL if no such data exists.
  */
 gpointer
 g_object_get_data (GObject     *object,
@@ -2941,7 +2945,7 @@ g_object_set_data (GObject     *object,
 }
 
 /**
- * g_object_set_data_full:
+ * g_object_set_data_full: (skip)
  * @object: #GObject containing the associations
  * @key: name of the key
  * @data: data to associate with that key
@@ -2974,7 +2978,7 @@ g_object_set_data_full (GObject       *object,
  * Remove a specified datum from the object's data associations,
  * without invoking the association's destroy handler.
  *
- * Returns: the data if found, or %NULL if no such data exists.
+ * Returns: (transfer full): the data if found, or %NULL if no such data exists.
  */
 gpointer
 g_object_steal_data (GObject     *object,
@@ -3084,7 +3088,7 @@ g_value_object_lcopy_value (const GValue *value,
 /**
  * g_value_set_object:
  * @value: a valid #GValue of %G_TYPE_OBJECT derived type
- * @v_object: object value to be set
+ * @v_object: (type GObject.Object): object value to be set
  *
  * Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object.
  *
@@ -3124,7 +3128,7 @@ g_value_set_object (GValue   *value,
 }
 
 /**
- * g_value_set_object_take_ownership:
+ * g_value_set_object_take_ownership: (skip)
  * @value: a valid #GValue of %G_TYPE_OBJECT derived type
  * @v_object: object value to be set
  *
@@ -3140,7 +3144,7 @@ g_value_set_object_take_ownership (GValue  *value,
 }
 
 /**
- * g_value_take_object:
+ * g_value_take_object: (skip)
  * @value: a valid #GValue of %G_TYPE_OBJECT derived type
  * @v_object: object value to be set
  *
@@ -3198,8 +3202,8 @@ g_value_get_object (const GValue *value)
  * Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing
  * its reference count.
  *
- * Returns: (type GObject.Object) (transfer full): object content of
- *          @value, should be unreferenced when no longer needed.
+ * Returns: (type GObject.Object) (transfer full): object content of @value,
+ *          should be unreferenced when no longer needed.
  */
 gpointer
 g_value_dup_object (const GValue *value)
@@ -3210,7 +3214,7 @@ g_value_dup_object (const GValue *value)
 }
 
 /**
- * g_signal_connect_object:
+ * g_signal_connect_object: (skip)
  * @instance: the instance to connect to.
  * @detailed_signal: a string of the form "signal-name::detail".
  * @c_handler: the #GCallback to connect.
@@ -3397,7 +3401,7 @@ g_object_watch_closure (GObject  *object,
  * @object and the created closure. This function is mainly useful
  * when implementing new types of closures.
  *
- * Returns: a newly allocated #GClosure
+ * Returns: (transfer full): a newly allocated #GClosure
  */
 GClosure*
 g_closure_new_object (guint    sizeof_closure,
@@ -3415,7 +3419,7 @@ g_closure_new_object (guint    sizeof_closure,
 }
 
 /**
- * g_cclosure_new_object:
+ * g_cclosure_new_object: (skip)
  * @callback_func: the function to invoke
  * @object: a #GObject pointer to pass to @callback_func
  *