[Bug 763213] Add documentation about _NAME macros vs. _get_name functions

[GStreamer (GNOME Bugzilla)]

https://bugzilla.gnome.org/show_bug.cgi?id=763213

Tim-Philipp Müller <t.i.m at zen.co.uk> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
 Attachment #323243|none                        |needs-work
             status|                            |

--- Comment #2 from Tim-Philipp Müller <t.i.m at zen.co.uk> ---
Comment on attachment 323243
  --> https://bugzilla.gnome.org/attachment.cgi?id=323243
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.

-- 
You are receiving this mail because:
You are the QA Contact for the bug.
You are the assignee for the bug.