GNOME Bugzilla – Bug 533856
gst_buffer_join() documentation is unclear
Last modified: 2008-08-20 07:22:05 UTC
The gst_buffer_join() documentation says that it unrefs the input parameters and mentions using their data without copying it. This suggests that the input parameters are made invalid, meaning I shouldn't use them again, regardless of their refcount. Is this true? Unrefing of input parameters is generally weird and awkward for language bindings, by the way.
> The gst_buffer_join() documentation says that it unrefs the input parameters > and mentions using their data without copying it. This suggests that the input > parameters are made invalid, meaning I shouldn't use them again, regardless of > their refcount. Is this true? No, this isn't true. In the case where no copying is done the input buffers are adjacent subbuffers of the same parent buffer, which makes the input buffer already not-writable (gst_buffer_is_writable), and the returned buffer will also be not writable in that case. The caller may keep a reference to the input buffers and in that case continue to access the data and metadata as it likes (within the usual constrains that are true for any buffer, ie. not modify the data if it's not writable and not modify the metadata if the metadata is not writable). (Anything else doesn't really make sense either, since any other piece of code, be it another element or the application, could still hold a reference to any of the input buffers.) Would be great if you could edit/extend the gtk-doc documentation blurb in gstutils.c so that it makes sense to you (doesn't have to be a patch if you don't have a checkout at hand): http://webcvs.freedesktop.org/gstreamer/gstreamer/gst/gstutils.c?view=markup > Unrefing of input parameters is generally weird and awkward for language > bindings, by the way. Well, it's a utility function for C programmers that want to avoid the tedious unrefs. You don't have to wrap it if it doesn't make sense in the context of your language binding.
Murray: ping? (releases coming up soon)
> Would be great if you could edit/extend the gtk-doc documentation blurb in > gstutils.c so that it makes sense to you Done. Thanks for the reminder. By the way, I notice that some documentation comments in that file use regular gtk-doc syntax, but some use doxygen/javadoc syntax. I presume gtk-doc somehow handles both, but it might be something you want to know about. > > Unrefing of input parameters is generally weird and awkward for language > > bindings, by the way. > Well, it's a utility function for C programmers that want to avoid the tedious > unrefs. You don't have to wrap it if it doesn't make sense in the context of > your language binding. So, "span" means the same as "join"? I'll probably add some more documentation that it's just a way of doing a gst_buffer_span(), and that it's not to be used by language bindings.
> By the way, I notice that some documentation comments in that file use regular > gtk-doc syntax, but some use doxygen/javadoc syntax. I presume gtk-doc somehow > handles both, but it might be something you want to know about. Oh really? Where? > So, "span" means the same as "join"? Basically yes, but span allows for offset/length parameters, so join is span(0,addedlength). > I'll probably add some more documentation that it's just a way of doing > gst_buffer_span(), and that it's not to be used by language bindings. It's just like gst_buffer_merge() only that _join() unrefs the input buffers.
gtk-doc definitely can't parse doxygen/javadoc style comments.
I can't see the doxygen-style comments now, so either it has changed or there was a problem with my optic nerve. Sorry. Leaving this bug open because I plan to improve the documentation.
murray, we would prefer to have bugs for specific issues. If you want to add some clarification to the docs of gst_buffer_join() we can do that. Please attach a patch, we can review and commit. For other docs improvments it would be nice to have separate tickets. So please close this if no change is needed.
Created attachment 116042 [details] [review] gst_buffer_join_docs.patch I said "done" above, but I don't seem to have done something. Maybe I lost it. Anyway, here's a patch that covers everything. Thanks for the explanation.
2008-08-20 Stefan Kost <ensonic@users.sf.net> patch by: Murray Cumming <murrayc@murrayc.com> * gst/gstutils.c: Mention that this is just like gst_buffer_merge() but with extra unreffing for C coders. Advise language bindings not to wrap it. Fixes Bug #533856. Also fix file comment.