GNOME Bugzilla – Bug 763213
Add documentation about _NAME macros vs. _get_name functions
Last modified: 2016-03-11 15:56:28 UTC
Created attachment 323243 [details] [review] extra documentation for GstObject & GstElement name macros & functions There are GST_OBJECT_NAME(), GST_ELEMENT_NAME(), gst_object_get_name(), gst_element_get_name() macros and functions. It can be confusing to distinguish these. This small commit adds notes to the documentation to clarify the differences.
Created attachment 323245 [details] [review] element: flesh out macro accessor docs a bit Just added some docs as well :)
Comment on attachment 323243 [details] [review] extra documentation for GstObject & GstElement name macros & functions As discussed on IRC.. >+ * It is recommended to use this instead of the GST_ELEMENT_NAME() macro, >+ * which is mostly useful for internal use in the core only. I don't know if GST_ELEMENT_NAME is really mostly only for internal use. It has its uses, it's just not thread-safe. >+ * This call is essentially the same as gst_object_get_name(), except that >+ * it can be directly used with GstElement pointers. Both the macro and _get_name() function calls are "used directly" with GstElement pointers? >+ * <warning><para> >+ * This returns the pointer to the internal name, which can be subject to >+ * external changes. It is not MT safe. In most cases, using the >+ * using gst_object_get_name() instead is the better choice. This macro >+ * is only really useful for internal use in the case and for cases when >+ * the implicit string copy this function performs must be avoided. >+ * </para></warning> This should not be a warning. And I'm not sure why the string copying of _get_name() is 'implicit' here.
Created attachment 323596 [details] [review] extra docs for element and object accessors Here's an updated version. It extends Tim's patch to GST_OBJECT_NAME and GST_OBJECT_PARENT , so both my and his patch are replaced by this. (For some reason, I can't mark both patches obsolete.)
Created attachment 323598 [details] [review] v2, small cleanup in the commit
Thanks commit f70dc95c35684ad12e7ad7a77c62bf0bcdab9972 Author: Carlos Rafael Giani <dv@pseudoterminal.org> Date: Thu Mar 10 10:35:40 2016 +0100 docs: Flesh out element and object macro accessor docs a bit https://bugzilla.gnome.org/show_bug.cgi?id=763213