gst: Correctly annotate functions taking floating reference parameters and returning floating references

https://bugzilla.gnome.org/show_bug.cgi?id=702960

14 files changed, 41 insertions, 24 deletions

diff --git a/gst/gstdevicemonitor.c b/gst/gstdevicemonitor.c
index 79c65ceb1..123d2849a 100644
--- a/gst/gstdevicemonitor.c
+++ b/gst/gstdevicemonitor.c
@@ -785,7 +785,7 @@ gst_device_monitor_remove_filter (GstDeviceMonitor * monitor, guint filter_id)
  *
  * Create a new #GstDeviceMonitor
  *
- * Returns: (transfer full): a new device monitor.
+ * Returns: (transfer floating): a new device monitor.
  *
  * Since: 1.4
  */
diff --git a/gst/gstdeviceprovider.c b/gst/gstdeviceprovider.c
index f5ba92ef7..8038d0204 100644
--- a/gst/gstdeviceprovider.c
+++ b/gst/gstdeviceprovider.c
@@ -543,13 +543,16 @@ gst_device_provider_get_bus (GstDeviceProvider * provider)
 /**
  * gst_device_provider_device_add:
  * @provider: a #GstDeviceProvider
- * @device: (transfer full): a #GstDevice that has been added
+ * @device: (transfer floating): a #GstDevice that has been added
  *
  * Posts a message on the provider's #GstBus to inform applications that
  * a new device has been added.
  *
  * This is for use by subclasses.
  *
+ * @device's reference count will be incremented, and any floating reference
+ * will be removed (see gst_object_ref_sink()).
+ *
  * Since: 1.4
  */
 void
@@ -568,8 +571,10 @@ gst_device_provider_device_add (GstDeviceProvider * provider,
   }
 
   GST_OBJECT_LOCK (provider);
-  provider->devices = g_list_prepend (provider->devices,
-      gst_object_ref (device));
+  /* Take an additional reference so we can be sure nobody removed it from the
+   * provider in the meantime and we can safely emit the message */
+  gst_object_ref (device);
+  provider->devices = g_list_prepend (provider->devices, device);
   GST_OBJECT_UNLOCK (provider);
 
   message = gst_message_new_device_added (GST_OBJECT (provider), device);
diff --git a/gst/gstelement.c b/gst/gstelement.c
index e4f68da57..231fd83c2 100644
--- a/gst/gstelement.c
+++ b/gst/gstelement.c
@@ -635,7 +635,7 @@ gst_element_get_index (GstElement * element)
 /**
  * gst_element_add_pad:
  * @element: a #GstElement to add the pad to.
- * @pad: (transfer full): the #GstPad to add to the element.
+ * @pad: (transfer floating): the #GstPad to add to the element.
  *
  * Adds a pad (link point) to @element. @pad's parent will be set to @element;
  * see gst_object_set_parent() for refcounting information.
@@ -1250,12 +1250,15 @@ gst_element_iterate_sink_pads (GstElement * element)
 /**
  * gst_element_class_add_pad_template:
  * @klass: the #GstElementClass to add the pad template to.
- * @templ: (transfer full): a #GstPadTemplate to add to the element class.
+ * @templ: (transfer floating): a #GstPadTemplate to add to the element class.
  *
  * Adds a padtemplate to an element class. This is mainly used in the _class_init
  * functions of classes. If a pad template with the same name as an already
  * existing one is added the old one is replaced by the new one.
  *
+ * @templ's reference count will be incremented, and any floating
+ * reference will be removed (see gst_object_ref_sink())
+ *
  */
 void
 gst_element_class_add_pad_template (GstElementClass * klass,
diff --git a/gst/gstghostpad.c b/gst/gstghostpad.c
index cd96668c2..478d2742b 100644
--- a/gst/gstghostpad.c
+++ b/gst/gstghostpad.c
@@ -658,7 +658,7 @@ construct_failed:
  *
  * The created ghostpad will not have a padtemplate.
  *
- * Returns: (transfer full) (nullable): a new #GstPad, or %NULL in
+ * Returns: (transfer floating) (nullable): a new #GstPad, or %NULL in
  * case of an error.
  */
 GstPad *
@@ -726,7 +726,7 @@ set_target_failed:
  *
  * Will ref the target.
  *
- * Returns: (transfer full) (nullable): a new #GstPad, or %NULL in
+ * Returns: (transfer floating) (nullable): a new #GstPad, or %NULL in
  * case of an error.
  */
 
@@ -769,7 +769,7 @@ set_target_failed:
  * Create a new ghostpad based on @templ, without setting a target. The
  * direction will be taken from the @templ.
  *
- * Returns: (transfer full) (nullable): a new #GstPad, or %NULL in
+ * Returns: (transfer floating) (nullable): a new #GstPad, or %NULL in
  * case of an error.
  */
 GstPad *
diff --git a/gst/gstobject.c b/gst/gstobject.c
index 50fa1c762..1bf9f724f 100644
--- a/gst/gstobject.c
+++ b/gst/gstobject.c
@@ -650,7 +650,7 @@ gst_object_get_name (GstObject * object)
 
 /**
  * gst_object_set_parent:
- * @object: a #GstObject
+ * @object: (transfer floating): a #GstObject
  * @parent: new parent of object
  *
  * Sets the parent of @object to @parent. The object's reference count will
@@ -1202,12 +1202,13 @@ gst_object_set_control_binding_disabled (GstObject * object,
 /**
  * gst_object_add_control_binding:
  * @object: the controller object
- * @binding: (transfer full): the #GstControlBinding that should be used
+ * @binding: (transfer floating): the #GstControlBinding that should be used
  *
  * Attach the #GstControlBinding to the object. If there already was a
  * #GstControlBinding for this property it will be replaced.
  *
- * The @object will take ownership of the @binding.
+ * The object's reference count will be incremented, and any floating
+ * reference will be removed (see gst_object_ref_sink())
  *
  * Returns: %FALSE if the given @binding has not been setup for this object or
  * has been setup for a non suitable property, %TRUE otherwise.
diff --git a/gst/gstpadtemplate.c b/gst/gstpadtemplate.c
index ce272cab7..8666ed1fa 100644
--- a/gst/gstpadtemplate.c
+++ b/gst/gstpadtemplate.c
@@ -284,7 +284,7 @@ G_DEFINE_POINTER_TYPE (GstStaticPadTemplate, gst_static_pad_template);
  *
  * Converts a #GstStaticPadTemplate into a #GstPadTemplate.
  *
- * Returns: (transfer full): a new #GstPadTemplate.
+ * Returns: (transfer floating): a new #GstPadTemplate.
  */
 /* FIXME0.11: rename to gst_pad_template_new_from_static_pad_template() */
 GstPadTemplate *
diff --git a/gst/gstplugin.c b/gst/gstplugin.c
index 7331a3146..ac27c16c7 100644
--- a/gst/gstplugin.c
+++ b/gst/gstplugin.c
@@ -710,6 +710,10 @@ extract_symname (const char *filename)
   return symname;
 }
 
+/* Note: The return value is (transfer full) although we work with floating
+ * references here. If a new plugin instance is created, it is always sinked
+ * in the registry first and a new reference is returned
+ */
 GstPlugin *
 _priv_gst_plugin_load_file_for_registry (const gchar * filename,
     GstRegistry * registry, GError ** error)
diff --git a/gst/gstregistry.c b/gst/gstregistry.c
index 198ca5f3f..983946ffc 100644
--- a/gst/gstregistry.c
+++ b/gst/gstregistry.c
@@ -410,10 +410,12 @@ gst_registry_get_path_list (GstRegistry * registry)
 /**
  * gst_registry_add_plugin:
  * @registry: the registry to add the plugin to
- * @plugin: (transfer full): the plugin to add
+ * @plugin: (transfer floating): the plugin to add
  *
  * Add the plugin to the registry. The plugin-added signal will be emitted.
- * This function will sink @plugin.
+ *
+ * @plugin's reference count will be incremented, and any floating
+ * reference will be removed (see gst_object_ref_sink())
  *
  * Returns: %TRUE on success.
  *
@@ -542,10 +544,12 @@ gst_registry_remove_plugin (GstRegistry * registry, GstPlugin * plugin)
 /**
  * gst_registry_add_feature:
  * @registry: the registry to add the plugin to
- * @feature: (transfer full): the feature to add
+ * @feature: (transfer floating): the feature to add
  *
  * Add the feature to the registry. The feature-added signal will be emitted.
- * This function sinks @feature.
+ *
+ * @feature's reference count will be incremented, and any floating
+ * reference will be removed (see gst_object_ref_sink())
  *
  * Returns: %TRUE on success.
  *
diff --git a/gst/gststreamcollection.c b/gst/gststreamcollection.c
index 5ad894094..c1d4674d2 100644
--- a/gst/gststreamcollection.c
+++ b/gst/gststreamcollection.c
@@ -184,7 +184,7 @@ gst_stream_collection_finalize (GObject * object)
  *
  * Create a new #GstStreamCollection.
  *
- * Returns: The new #GstStreamCollection.
+ * Returns: (transfer floating): The new #GstStreamCollection.
  *
  * Since: 1.10
  */
diff --git a/gst/gststreams.c b/gst/gststreams.c
index b61e61b45..8873aad56 100644
--- a/gst/gststreams.c
+++ b/gst/gststreams.c
@@ -210,7 +210,7 @@ gst_stream_finalize (GObject * object)
  * Create a new #GstStream for the given @stream_id, @caps, @type
  * and @flags
  *
- * Returns: The new #GstStream
+ * Returns: (transfer floating): The new #GstStream
  *
  * Since: 1.10
  */
diff --git a/gst/gsttracerrecord.c b/gst/gsttracerrecord.c
index c6651d212..889479dce 100644
--- a/gst/gsttracerrecord.c
+++ b/gst/gsttracerrecord.c
@@ -178,7 +178,7 @@ gst_tracer_record_init (GstTracerRecord * self)
  *
  * > Please note that this is still under discussion and subject to change.
  *
- * Returns: a new #GstTracerRecord
+ * Returns: (transfer floating): a new #GstTracerRecord
  */
 GstTracerRecord *
 gst_tracer_record_new (const gchar * name, const gchar * firstfield, ...)
diff --git a/gst/gstutils.c b/gst/gstutils.c
index 94fb51369..3d26d47b9 100644
--- a/gst/gstutils.c
+++ b/gst/gstutils.c
@@ -2567,8 +2567,8 @@ gst_object_default_error (GstObject * source, const GError * error,
 /**
  * gst_bin_add_many:
  * @bin: a #GstBin
- * @element_1: (transfer full): the #GstElement element to add to the bin
- * @...: (transfer full): additional elements to add to the bin
+ * @element_1: (transfer floating): the #GstElement element to add to the bin
+ * @...: (transfer floating): additional elements to add to the bin
  *
  * Adds a %NULL-terminated list of elements to a bin.  This function is
  * equivalent to calling gst_bin_add() for each member of the list. The return
diff --git a/libs/gst/controller/gstproxycontrolbinding.c b/libs/gst/controller/gstproxycontrolbinding.c
index 17a08a7d5..660a3df8e 100644
--- a/libs/gst/controller/gstproxycontrolbinding.c
+++ b/libs/gst/controller/gstproxycontrolbinding.c
@@ -174,7 +174,7 @@ gst_proxy_control_binding_class_init (GstProxyControlBindingClass * klass)
  * requests from @property_name on @object to the control binding at
  * @ref_property_name on @ref_object.
  *
- * Returns: a new #GstControlBinding that proxies the control interface between
+ * Returns: (transfer floating): a new #GstControlBinding that proxies the control interface between
  * properties on different #GstObject's
  *
  * Since: 1.12
diff --git a/libs/gst/net/gstnettimeprovider.c b/libs/gst/net/gstnettimeprovider.c
index fee3ec125..0c0ef69ca 100644
--- a/libs/gst/net/gstnettimeprovider.c
+++ b/libs/gst/net/gstnettimeprovider.c
@@ -434,7 +434,7 @@ gst_net_time_provider_initable_iface_init (gpointer g_iface)
  *
  * Allows network clients to get the current time of @clock.
  *
- * Returns: the new #GstNetTimeProvider, or NULL on error
+ * Returns: (transfer floating): the new #GstNetTimeProvider, or NULL on error
  */
 GstNetTimeProvider *
 gst_net_time_provider_new (GstClock * clock, const gchar * address, gint port)