After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 788477 - gst_object_ref_sink() documentation is confusing
gst_object_ref_sink() documentation is confusing
Status: RESOLVED WONTFIX
Product: GStreamer
Classification: Platform
Component: documentation
1.0.1
Other All
: Normal normal
: git master
Assigned To: GStreamer Maintainers
GStreamer Maintainers
Depends on:
Blocks:
 
 
Reported: 2017-10-03 15:21 UTC by Alicia Boya García
Modified: 2018-01-12 18:48 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
Patch (1.43 KB, patch)
2017-10-07 18:41 UTC, Alicia Boya García
none Details | Review

Description Alicia Boya García 2017-10-03 15:21:26 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.
Comment 1 Nicolas Dufresne (ndufresne) 2017-10-03 15:54:32 UTC
The second part is the correct part. We could also just redirect to g_object_ref_sink() documentation, this is just a redirection really.
Comment 2 Nicolas Dufresne (ndufresne) 2017-10-03 15:55:27 UTC
Haha, funny, GLib got the same text copy pasted. We should definatly fix both then ;-P
Comment 3 Alicia Boya García 2017-10-07 18:41:17 UTC
Created attachment 361105 [details] [review]
Patch
Comment 4 Sebastian Dröge (slomo) 2017-10-09 07:03:53 UTC
"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.
Comment 5 Nicolas Dufresne (ndufresne) 2017-12-06 21:50:41 UTC
Review of attachment 361105 [details] [review]:

I think it's better indeed.
Comment 6 Nicolas Dufresne (ndufresne) 2017-12-06 21:51:53 UTC
(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 ...
Comment 7 Tim-Philipp Müller 2018-01-12 18:48:18 UTC
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.