[Bug 702960] gst_element_add_pad()'s pad parameter should be marked as transfer none

[GStreamer (bugzilla.gnome.org)]

https://bugzilla.gnome.org/show_bug.cgi?id=702960
  GStreamer | gstreamer (core) | git

--- Comment #15 from Simon Feltman <s.feltman at gmail.com> 2013-07-26 22:49:08 UTC ---
(In reply to comment #14)
> It's also important to C developers, and it would be nice to differentiate
> between these cases from a documentation annotation point of view at least.
> 
> Otherwise... a function that is (transfer none) and just calls g_object_ref()
> on the parameter will behave different than a function that has (transfer none)
> and calls g_object_ref_sink().

Ok, that makes sense and seems like it would be nice. The C API user should be
provided with certainty as to what is going to occur with the reference.
Without this, they have to make a best guess based on if the API uses
GInitiallyUnowned, transfer full/none, usage of g_object_new, and possibly
looking at the functions source code; which is unreasonable.

Although I'm not sure if using (transfer floating) to denote this is very clear
either, at least makes some type of distinction. I would hope (transfer
floating) could be reserved for functions which always return a floating ref.
For arguments, you want specificity as to whether or not the function sinks it,
not that the argument may or may not be floating. Although you could derive
this meaning, it might be confusing when reading API docs and seeing it for an
argument: "does this mean I need to call force_floating on the argument before
passing it in?"

If what you are trying to achieve is API clarity, you don't necessarily need a
GI annotation to do that. Looking back at the Python docs, each function could
just say something like: "Note: This function will "sink" floating references
for the element argument.", albeit that is pretty tedious.

> From a bindings point of view this distinction probably doesn't matter as
> bindings probably already do g_object_ref_sink() themselves right after they
> got the object if it was floating.

Yep, at least for functions with a return annotated as (transfer none) along
with some special case hacks.

-- 
Configure bugmail: https://bugzilla.gnome.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug.
You are the assignee for the bug.