From f70dc95c35684ad12e7ad7a77c62bf0bcdab9972 Mon Sep 17 00:00:00 2001
From: Carlos Rafael Giani <dv@pseudoterminal.org>
Date: Thu, 10 Mar 2016 10:35:40 +0100
Subject: [PATCH] docs: Flesh out element and object macro accessor docs a bit

https://bugzilla.gnome.org/show_bug.cgi?id=763213
---
 gst/gstelement.h | 17 ++++++++++++-----
 gst/gstobject.h  |  8 ++++++--
 2 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/gst/gstelement.h b/gst/gstelement.h
index c3d1cbd..f4bed31 100644
--- a/gst/gstelement.h
+++ b/gst/gstelement.h
@@ -346,8 +346,9 @@ typedef enum
  * GST_ELEMENT_NAME:
  * @elem: A #GstElement to query
  *
- * Gets the name of this element. Use only in core as this is not
- * ABI-compatible. Others use gst_element_get_name()
+ * Gets the name of this element. This is not thread-safe by default
+ * (i.e. you will have to make sure the object lock is taken yourself).
+ * If in doubt use gst_element_get_name() instead.
  */
 #define GST_ELEMENT_NAME(elem)                  (GST_OBJECT_NAME(elem))
 
@@ -355,7 +356,9 @@ typedef enum
  * GST_ELEMENT_PARENT:
  * @elem: A #GstElement to query
  *
- * Get the parent object of this element.
+ * Get the parent object of this element. This is not thread-safe by default
+ * (i.e. you will have to make sure the object lock is taken yourself).
+ * If in doubt use gst_object_get_parent() instead.
  */
 #define GST_ELEMENT_PARENT(elem)                (GST_ELEMENT_CAST(GST_OBJECT_PARENT(elem)))
 
@@ -363,7 +366,9 @@ typedef enum
  * GST_ELEMENT_BUS:
  * @elem: A #GstElement to query
  *
- * Get the message bus of this element.
+ * Get the message bus of this element. This is not thread-safe by default
+ * (i.e. you will have to make sure the object lock is taken yourself).
+ * If in doubt use gst_element_get_bus() instead.
  */
 #define GST_ELEMENT_BUS(elem)                   (GST_ELEMENT_CAST(elem)->bus)
 
@@ -371,7 +376,9 @@ typedef enum
  * GST_ELEMENT_CLOCK:
  * @elem: A #GstElement to query
  *
- * Get the clock of this element
+ * Get the clock of this element.This is not thread-safe by default
+ * (i.e. you will have to make sure it is safe yourself).
+ * If in doubt use gst_element_get_clock() instead.
  */
 #define GST_ELEMENT_CLOCK(elem)                 (GST_ELEMENT_CAST(elem)->clock)
 
diff --git a/gst/gstobject.h b/gst/gstobject.h
index f5b9b36..ad033e8 100644
--- a/gst/gstobject.h
+++ b/gst/gstobject.h
@@ -105,14 +105,18 @@ typedef enum
  * GST_OBJECT_NAME:
  * @obj: a #GstObject
  *
- * Get the name of this object
+ * Get the name of this object. This is not thread-safe by default
+ * (i.e. you will have to make sure the object lock is taken yourself).
+ * If in doubt use gst_object_get_name() instead.
  */
 #define GST_OBJECT_NAME(obj)            (GST_OBJECT_CAST(obj)->name)
 /**
  * GST_OBJECT_PARENT:
  * @obj: a #GstObject
  *
- * Get the parent of this object
+ * Get the parent of this object. This is not thread-safe by default
+ * (i.e. you will have to make sure the object lock is taken yourself).
+ * If in doubt use gst_object_get_parent() instead.
  */
 #define GST_OBJECT_PARENT(obj)          (GST_OBJECT_CAST(obj)->parent)
 
-- 
2.7.4