GNOME Bugzilla – Bug 788477
gst_object_ref_sink() documentation is confusing
Last modified: 2018-01-12 18:48:18 UTC
The current documentation of gst_object_ref_sink() reads like this: > Increase the reference count of object , and possibly remove the floating > reference, if object has a floating reference. > > In other words, if the object is floating, then this call "assumes ownership" > of the floating reference, converting it to a normal reference by clearing the > floating flag while leaving the reference count unchanged. If the object is not > floating, then this call adds a new normal reference increasing the reference > count by one. The first paragraph seems to contradict the second one: the first one seems to claim that the reference count is unconditionally increased, while the second one states that is only done if the reference is not currently floating.
The second part is the correct part. We could also just redirect to g_object_ref_sink() documentation, this is just a redirection really.
Haha, funny, GLib got the same text copy pasted. We should definatly fix both then ;-P
Created attachment 361105 [details] [review] Patch
"remove the floating reference" means that it decreases the reference count by one (and unset the floating flag) if the floating flag was set. The original documentation is IMHO fine, and to really understand what all that means one has to read the GObject docs about floating references anyway :) Maybe a link to that would be useful.
Review of attachment 361105 [details] [review]: I think it's better indeed.
(In reply to Sebastian Dröge (slomo) from comment #4) > "remove the floating reference" means that it decreases the reference count > by one (and unset the floating flag) if the floating flag was set. > > The original documentation is IMHO fine, and to really understand what all > that means one has to read the GObject docs about floating references anyway > :) Maybe a link to that would be useful. Gst doc is a copy paste from the GObject doc, it still pretty hard to make sense out of it. Maybe there isn't a great solution to that anyway ...
Thanks for the bug report and the patch. I can see how it can be confusing, but floating references are confusing in general. I think the text is clearer as is, with the preamble and the 'In other words' follow-up. If anyone strongly feels otherwise, by all means feel free to push whatever you feel makes it all better and perhaps also suggest the same for GLib, but in the mean time let's close this to reduce bugzilla clutter. Thanks :) I've added a comment refering explicitly to the GObject docs for more info about floating references.