docs: convert NULL, TRUE, and FALSE to %NULL, %TRUE, and %FALSE
[platform/upstream/gstreamer.git] / gst / gsttaglist.c
index eecc8a1..0eac36d 100644 (file)
@@ -15,8 +15,8 @@
  *
  * You should have received a copy of the GNU Library General Public
  * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+ * Boston, MA 02110-1301, USA.
  */
 
 /**
@@ -25,9 +25,8 @@
  *
  * List of tags and values used to describe media metadata.
  *
- * Strings must be in ASCII or UTF-8 encoding. No other encodings are allowed.
- *
- * Last reviewed on 2009-06-09 (0.10.23)
+ * Strings in structures must be ASCII or UTF-8 encoded. Other encodings are
+ * not allowed. Strings must not be empty or %NULL.
  */
 
 #ifdef HAVE_CONFIG_H
@@ -57,9 +56,11 @@ typedef struct _GstTagListImpl
   GstTagList taglist;
 
   GstStructure *structure;
+  GstTagScope scope;
 } GstTagListImpl;
 
 #define GST_TAG_LIST_STRUCTURE(taglist)  ((GstTagListImpl*)(taglist))->structure
+#define GST_TAG_LIST_SCOPE(taglist)  ((GstTagListImpl*)(taglist))->scope
 
 typedef struct
 {
@@ -314,7 +315,7 @@ _priv_gst_tag_initialize (void)
           "or produced"), NULL);
   gst_tag_register_static (GST_TAG_GEO_LOCATION_SUBLOCATION, GST_TAG_FLAG_META,
       G_TYPE_STRING, _("geo location sublocation"),
-      _("a location whithin a city where the media has been produced "
+      _("a location within a city where the media has been produced "
           "or created (e.g. the neighborhood)"), NULL);
   gst_tag_register_static (GST_TAG_GEO_LOCATION_HORIZONTAL_ERROR,
       GST_TAG_FLAG_META, G_TYPE_DOUBLE, _("geo location horizontal error"),
@@ -380,11 +381,23 @@ _priv_gst_tag_initialize (void)
       G_TYPE_STRING, _("application name"),
       _("Application used to create the media"), NULL);
   gst_tag_register_static (GST_TAG_APPLICATION_DATA, GST_TAG_FLAG_META,
-      GST_TYPE_BUFFER, _("application data"),
+      GST_TYPE_SAMPLE, _("application data"),
       _("Arbitrary application data to be serialized into the media"), NULL);
   gst_tag_register_static (GST_TAG_IMAGE_ORIENTATION, GST_TAG_FLAG_META,
       G_TYPE_STRING, _("image orientation"),
       _("How the image should be rotated or flipped before display"), NULL);
+  gst_tag_register_static (GST_TAG_PUBLISHER, GST_TAG_FLAG_META,
+      G_TYPE_STRING,
+      _("publisher"),
+      _("Name of the label or publisher"), gst_tag_merge_strings_with_comma);
+  gst_tag_register_static (GST_TAG_INTERPRETED_BY, GST_TAG_FLAG_META,
+      G_TYPE_STRING,
+      _("interpreted-by"),
+      _("Information about the people behind a remix and similar "
+          "interpretations"), gst_tag_merge_strings_with_comma);
+  gst_tag_register_static (GST_TAG_MIDI_BASE_NOTE, GST_TAG_FLAG_META,
+      G_TYPE_UINT,
+      _("midi-base-note"), _("Midi note number of the audio track."), NULL);
 }
 
 /**
@@ -452,7 +465,7 @@ gst_tag_lookup (const gchar * tag_name)
  * @type: the type this data is in
  * @nick: human-readable name
  * @blurb: a human-readable description about this tag
- * @func: function for merging multiple values of this tag, or NULL
+ * @func: (allow-none): function for merging multiple values of this tag, or %NULL
  *
  * Registers a new tag type for the use with GStreamer's type system. If a type
  * with that name is already registered, that one is used.
@@ -461,7 +474,7 @@ gst_tag_lookup (const gchar * tag_name)
  *
  * Important: if you do not supply a merge function the implication will be
  * that there can only be one single value for this tag in a tag list and
- * any additional values will silenty be discarded when being added (unless
+ * any additional values will silently be discarded when being added (unless
  * #GST_TAG_MERGE_REPLACE, #GST_TAG_MERGE_REPLACE_ALL, or
  * #GST_TAG_MERGE_PREPEND is used as merge mode, in which case the new
  * value will replace the old one in the list).
@@ -496,7 +509,7 @@ gst_tag_register (const gchar * name, GstTagFlag flag, GType type,
  * @type: the type this data is in
  * @nick: human-readable name or short description (string constant)
  * @blurb: a human-readable description for this tag (string constant)
- * @func: function for merging multiple values of this tag, or NULL
+ * @func: (allow-none): function for merging multiple values of this tag, or %NULL
  *
  * Registers a new tag type for the use with GStreamer's type system.
  *
@@ -542,7 +555,7 @@ gst_tag_register_static (const gchar * name, GstTagFlag flag, GType type,
  *
  * Checks if the given type is already registered.
  *
- * Returns: TRUE if the type is already registered
+ * Returns: %TRUE if the type is already registered
  */
 gboolean
 gst_tag_exists (const gchar * tag)
@@ -641,7 +654,7 @@ gst_tag_get_flag (const gchar * tag)
  * Checks if the given tag is fixed. A fixed tag can only contain one value.
  * Unfixed tags can contain lists of values.
  *
- * Returns: TRUE, if the given tag is fixed.
+ * Returns: %TRUE, if the given tag is fixed.
  */
 gboolean
 gst_tag_is_fixed (const gchar * tag)
@@ -665,11 +678,12 @@ gst_tag_list_new_internal (GstStructure * s)
 
   tag_list = (GstTagList *) g_slice_new (GstTagListImpl);
 
-  gst_mini_object_init (GST_MINI_OBJECT_CAST (tag_list), GST_TYPE_TAG_LIST,
+  gst_mini_object_init (GST_MINI_OBJECT_CAST (tag_list), 0, GST_TYPE_TAG_LIST,
       (GstMiniObjectCopyFunction) __gst_tag_list_copy, NULL,
       (GstMiniObjectFreeFunction) __gst_tag_list_free);
 
   GST_TAG_LIST_STRUCTURE (tag_list) = s;
+  GST_TAG_LIST_SCOPE (tag_list) = GST_TAG_SCOPE_STREAM;
 
 #ifdef DEBUG_REFCOUNT
   GST_CAT_TRACE (GST_CAT_TAGS, "created taglist %p", tag_list);
@@ -726,22 +740,24 @@ gst_tag_list_new_empty (void)
 /**
  * gst_tag_list_new:
  * @tag: tag
- * @...: NULL-terminated list of values to set
+ * @...: %NULL-terminated list of values to set
  *
  * Creates a new taglist and appends the values for the given tags. It expects
- * tag-value pairs like gst_tag_list_add(), and a NULL terminator after the
+ * tag-value pairs like gst_tag_list_add(), and a %NULL terminator after the
  * last pair. The type of the values is implicit and is documented in the API
  * reference, but can also be queried at runtime with gst_tag_get_type(). It
  * is an error to pass a value of a type not matching the tag type into this
  * function. The tag list will make copies of any arguments passed
  * (e.g. strings, buffers).
  *
+ * After creation you might also want to set a #GstTagScope on the returned
+ * taglist to signal if the contained tags are global or stream tags. By
+ * default stream scope is assumes. See gst_tag_list_set_scope().
+ *
  * Free-function: gst_tag_list_unref
  *
  * Returns: (transfer full): a new #GstTagList. Free with gst_tag_list_unref()
  *     when no longer needed.
- *
- * Since: 0.10.24
  */
 GstTagList *
 gst_tag_list_new (const gchar * tag, ...)
@@ -770,8 +786,6 @@ gst_tag_list_new (const gchar * tag, ...)
  *
  * Returns: (transfer full): a new #GstTagList. Free with gst_tag_list_unref()
  *     when no longer needed.
- *
- * Since: 0.10.24
  */
 GstTagList *
 gst_tag_list_new_valist (va_list var_args)
@@ -788,15 +802,47 @@ gst_tag_list_new_valist (va_list var_args)
 }
 
 /**
+ * gst_tag_list_set_scope:
+ * @list: a #GstTagList
+ * @scope: new scope for @list
+ *
+ * Sets the scope of @list to @scope. By default the scope
+ * of a taglist is stream scope.
+ *
+ */
+void
+gst_tag_list_set_scope (GstTagList * list, GstTagScope scope)
+{
+  g_return_if_fail (GST_IS_TAG_LIST (list));
+  g_return_if_fail (gst_tag_list_is_writable (list));
+
+  GST_TAG_LIST_SCOPE (list) = scope;
+}
+
+/**
+ * gst_tag_list_get_scope:
+ * @list: a #GstTagList
+ *
+ * Gets the scope of @list.
+ *
+ * Returns: The scope of @list
+ */
+GstTagScope
+gst_tag_list_get_scope (const GstTagList * list)
+{
+  g_return_val_if_fail (GST_IS_TAG_LIST (list), GST_TAG_SCOPE_STREAM);
+
+  return GST_TAG_LIST_SCOPE (list);
+}
+
+/**
  * gst_tag_list_to_string:
  * @list: a #GstTagList
  *
  * Serializes a tag list to a string.
  *
- * Returns: a newly-allocated string, or NULL in case of an error. The
+ * Returns: a newly-allocated string, or %NULL in case of an error. The
  *    string must be freed with g_free() when no longer needed.
- *
- * Since: 0.10.36
  */
 gchar *
 gst_tag_list_to_string (const GstTagList * list)
@@ -812,19 +858,23 @@ gst_tag_list_to_string (const GstTagList * list)
  *
  * Deserializes a tag list.
  *
- * Returns: a new #GstTagList, or NULL in case of an error.
- *
- * Since: 0.10.36
+ * Returns: a new #GstTagList, or %NULL in case of an error.
  */
 GstTagList *
 gst_tag_list_new_from_string (const gchar * str)
 {
   GstTagList *tag_list;
+  GstStructure *s;
 
   g_return_val_if_fail (str != NULL, NULL);
   g_return_val_if_fail (g_str_has_prefix (str, "taglist"), NULL);
 
-  tag_list = gst_tag_list_new_internal (gst_structure_from_string (str, NULL));
+  s = gst_structure_from_string (str, NULL);
+  if (s == NULL)
+    return NULL;
+
+  tag_list = gst_tag_list_new_internal (s);
+
   return tag_list;
 }
 
@@ -869,9 +919,7 @@ gst_tag_list_nth_tag_name (const GstTagList * list, guint index)
  *
  * Checks if the given taglist is empty.
  *
- * Returns: TRUE if the taglist is empty, otherwise FALSE.
- *
- * Since: 0.10.11
+ * Returns: %TRUE if the taglist is empty, otherwise %FALSE.
  */
 gboolean
 gst_tag_list_is_empty (const GstTagList * list)
@@ -910,9 +958,7 @@ gst_tag_list_fields_equal (const GValue * value1, const GValue * value2)
  *
  * Checks if the two given taglists are equal.
  *
- * Returns: TRUE if the taglists are equal, otherwise FALSE
- *
- * Since: 0.10.36
+ * Returns: %TRUE if the taglists are equal, otherwise %FALSE
  */
 gboolean
 gst_tag_list_is_equal (const GstTagList * list1, const GstTagList * list2)
@@ -976,6 +1022,14 @@ gst_tag_list_add_value_internal (GstTagList * tag_list, GstTagMergeMode mode,
     }
   }
 
+  if (G_UNLIKELY (!G_VALUE_HOLDS (value, info->type) &&
+          !GST_VALUE_HOLDS_LIST (value))) {
+    g_warning ("tag '%s' should hold value of type '%s', but value of "
+        "type '%s' passed", info->nick, g_type_name (info->type),
+        g_type_name (G_VALUE_TYPE (value)));
+    return;
+  }
+
   tag_quark = info->name_quark;
 
   if (info->merge_func
@@ -988,14 +1042,20 @@ gst_tag_list_add_value_internal (GstTagList * tag_list, GstTagMergeMode mode,
         gst_structure_id_set_value (list, tag_quark, value);
         break;
       case GST_TAG_MERGE_PREPEND:
-        gst_value_list_merge (&dest, value, value2);
-        gst_structure_id_set_value (list, tag_quark, &dest);
-        g_value_unset (&dest);
+        if (GST_VALUE_HOLDS_LIST (value2) && !GST_VALUE_HOLDS_LIST (value))
+          gst_value_list_prepend_value ((GValue *) value2, value);
+        else {
+          gst_value_list_merge (&dest, value, value2);
+          gst_structure_id_take_value (list, tag_quark, &dest);
+        }
         break;
       case GST_TAG_MERGE_APPEND:
-        gst_value_list_merge (&dest, value2, value);
-        gst_structure_id_set_value (list, tag_quark, &dest);
-        g_value_unset (&dest);
+        if (GST_VALUE_HOLDS_LIST (value2) && !GST_VALUE_HOLDS_LIST (value))
+          gst_value_list_append_value ((GValue *) value2, value);
+        else {
+          gst_value_list_merge (&dest, value2, value);
+          gst_structure_id_take_value (list, tag_quark, &dest);
+        }
         break;
       case GST_TAG_MERGE_KEEP:
       case GST_TAG_MERGE_KEEP_ALL:
@@ -1072,8 +1132,8 @@ gst_tag_list_insert (GstTagList * into, const GstTagList * from,
  * @list2: second list to merge
  * @mode: the mode to use
  *
- * Merges the two given lists into a new list. If one of the lists is NULL, a
- * copy of the other is returned. If both lists are NULL, NULL is returned.
+ * Merges the two given lists into a new list. If one of the lists is %NULL, a
+ * copy of the other is returned. If both lists are %NULL, %NULL is returned.
  *
  * Free-function: gst_tag_list_unref
  *
@@ -1137,7 +1197,7 @@ gst_tag_list_get_tag_size (const GstTagList * list, const gchar * tag)
  * @list: list to set tags in
  * @mode: the mode to use
  * @tag: tag
- * @...: NULL-terminated list of values to set
+ * @...: %NULL-terminated list of values to set
  *
  * Sets the values for the given tags using the specified mode.
  */
@@ -1224,7 +1284,13 @@ gst_tag_list_add_valist (GstTagList * list, GstTagMergeMode mode,
        */
       return;
     }
-    gst_tag_list_add_value_internal (list, mode, tag, &value, info);
+    /* Facilitate GstBuffer -> GstSample transition */
+    if (G_UNLIKELY (info->type == GST_TYPE_SAMPLE &&
+            !GST_IS_SAMPLE (value.data[0].v_pointer))) {
+      g_warning ("Expected GstSample argument for tag '%s'", tag);
+    } else {
+      gst_tag_list_add_value_internal (list, mode, tag, &value, info);
+    }
     g_value_unset (&value);
     tag = va_arg (var_args, gchar *);
   }
@@ -1274,8 +1340,6 @@ gst_tag_list_add_valist_values (GstTagList * list, GstTagMergeMode mode,
  * @value: GValue for this tag
  *
  * Sets the GValue for a given tag using the specified mode.
- *
- * Since: 0.10.24
  */
 void
 gst_tag_list_add_value (GstTagList * list, GstTagMergeMode mode,
@@ -1357,7 +1421,7 @@ gst_tag_list_foreach (const GstTagList * list, GstTagForeachFunc func,
  * Gets the value that is at the given index for the given tag in the given
  * list.
  *
- * Returns: (transfer none): The GValue for the specified entry or NULL if the
+ * Returns: (transfer none): The GValue for the specified entry or %NULL if the
  *          tag wasn't available or the tag doesn't have as many entries
  */
 const GValue *
@@ -1395,7 +1459,7 @@ gst_tag_list_get_value_index (const GstTagList * list, const gchar * tag,
  * with the tag.
  * You must g_value_unset() the value after use.
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *          given list.
  */
 gboolean
@@ -1485,7 +1549,7 @@ gst_tag_list_get_ ## name ## _index (const GstTagList *list,            \
  * Copies the contents for the given tag into the value, merging multiple values
  * into one if multiple values are associated with the tag.
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 /**
@@ -1498,7 +1562,7 @@ gst_tag_list_get_ ## name ## _index (const GstTagList *list,            \
  * Gets the value that is at the given index for the given tag in the given
  * list.
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 TAG_MERGE_FUNCS (boolean, gboolean, TRUE);
@@ -1511,7 +1575,7 @@ TAG_MERGE_FUNCS (boolean, gboolean, TRUE);
  * Copies the contents for the given tag into the value, merging multiple values
  * into one if multiple values are associated with the tag.
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 /**
@@ -1524,7 +1588,7 @@ TAG_MERGE_FUNCS (boolean, gboolean, TRUE);
  * Gets the value that is at the given index for the given tag in the given
  * list.
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 TAG_MERGE_FUNCS (int, gint, TRUE);
@@ -1537,7 +1601,7 @@ TAG_MERGE_FUNCS (int, gint, TRUE);
  * Copies the contents for the given tag into the value, merging multiple values
  * into one if multiple values are associated with the tag.
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 /**
@@ -1550,7 +1614,7 @@ TAG_MERGE_FUNCS (int, gint, TRUE);
  * Gets the value that is at the given index for the given tag in the given
  * list.
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 TAG_MERGE_FUNCS (uint, guint, TRUE);
@@ -1564,7 +1628,7 @@ TAG_MERGE_FUNCS (uint, guint, TRUE);
  * Gets the value that is at the given index for the given tag in the given
  * list.
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 TAG_MERGE_FUNCS (int64, gint64, TRUE);
@@ -1577,7 +1641,7 @@ TAG_MERGE_FUNCS (int64, gint64, TRUE);
  * Copies the contents for the given tag into the value, merging multiple values
  * into one if multiple values are associated with the tag.
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 /**
@@ -1590,7 +1654,7 @@ TAG_MERGE_FUNCS (int64, gint64, TRUE);
  * Gets the value that is at the given index for the given tag in the given
  * list.
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 TAG_MERGE_FUNCS (uint64, guint64, TRUE);
@@ -1603,7 +1667,7 @@ TAG_MERGE_FUNCS (uint64, guint64, TRUE);
  * Copies the contents for the given tag into the value, merging multiple values
  * into one if multiple values are associated with the tag.
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 /**
@@ -1616,7 +1680,7 @@ TAG_MERGE_FUNCS (uint64, guint64, TRUE);
  * Gets the value that is at the given index for the given tag in the given
  * list.
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 TAG_MERGE_FUNCS (float, gfloat, TRUE);
@@ -1629,7 +1693,7 @@ TAG_MERGE_FUNCS (float, gfloat, TRUE);
  * Copies the contents for the given tag into the value, merging multiple values
  * into one if multiple values are associated with the tag.
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 /**
@@ -1642,7 +1706,7 @@ TAG_MERGE_FUNCS (float, gfloat, TRUE);
  * Gets the value that is at the given index for the given tag in the given
  * list.
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 TAG_MERGE_FUNCS (double, gdouble, TRUE);
@@ -1655,7 +1719,7 @@ TAG_MERGE_FUNCS (double, gdouble, TRUE);
  * Copies the contents for the given tag into the value, merging multiple values
  * into one if multiple values are associated with the tag.
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 /**
@@ -1668,7 +1732,7 @@ TAG_MERGE_FUNCS (double, gdouble, TRUE);
  * Gets the value that is at the given index for the given tag in the given
  * list.
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 TAG_MERGE_FUNCS (pointer, gpointer, (*value != NULL));
@@ -1698,12 +1762,12 @@ _gst_strdup0 (const gchar * s)
  * to retrieve the first string associated with this tag unmodified.
  *
  * The resulting string in @value will be in UTF-8 encoding and should be
- * freed by the caller using g_free when no longer needed. Since 0.10.24 the
- * returned string is also guaranteed to be non-NULL and non-empty.
+ * freed by the caller using g_free when no longer needed. The
+ * returned string is also guaranteed to be non-%NULL and non-empty.
  *
  * Free-function: g_free
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 /**
@@ -1717,12 +1781,12 @@ _gst_strdup0 (const gchar * s)
  * list.
  *
  * The resulting string in @value will be in UTF-8 encoding and should be
- * freed by the caller using g_free when no longer needed. Since 0.10.24 the
- * returned string is also guaranteed to be non-NULL and non-empty.
+ * freed by the caller using g_free when no longer needed. The
+ * returned string is also guaranteed to be non-%NULL and non-empty.
  *
  * Free-function: g_free
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
  *              given list.
  */
 TAG_MERGE_FUNCS (string, gchar *, (*value != NULL));
@@ -1744,9 +1808,9 @@ TAG_MERGE_FUNCS (string, gchar *, (*value != NULL));
  *
  * The resulting string in @value will be in UTF-8 encoding and doesn't need
  * to be freed by the caller. The returned string is also guaranteed to
- * be non-NULL and non-empty.
+ * be non-%NULL and non-empty.
  *
- * Returns: TRUE, if a value was set, FALSE if the tag didn't exist in the
+ * Returns: %TRUE, if a value was set, %FALSE if the tag didn't exist in the
  *              given list.
  */
 gboolean
@@ -1778,8 +1842,8 @@ gst_tag_list_peek_string_index (const GstTagList * list,
  *
  * Free-function: g_date_free
  *
- * Returns: TRUE, if a date was copied, FALSE if the tag didn't exist in the
- *              given list or if it was #NULL.
+ * Returns: %TRUE, if a date was copied, %FALSE if the tag didn't exist in the
+ *              given list or if it was %NULL.
  */
 gboolean
 gst_tag_list_get_date (const GstTagList * list, const gchar * tag,
@@ -1811,8 +1875,8 @@ gst_tag_list_get_date (const GstTagList * list, const gchar * tag,
  *
  * Free-function: g_date_free
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
- *              given list or if it was #NULL.
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
+ *              given list or if it was %NULL.
  */
 gboolean
 gst_tag_list_get_date_index (const GstTagList * list,
@@ -1843,10 +1907,8 @@ gst_tag_list_get_date_index (const GstTagList * list,
  *
  * Free-function: gst_date_time_unref
  *
- * Returns: TRUE, if a datetime was copied, FALSE if the tag didn't exist in
- *              thegiven list or if it was #NULL.
- *
- * Since: 0.10.31
+ * Returns: %TRUE, if a datetime was copied, %FALSE if the tag didn't exist in
+ *              the given list or if it was %NULL.
  */
 gboolean
 gst_tag_list_get_date_time (const GstTagList * list, const gchar * tag,
@@ -1881,10 +1943,8 @@ gst_tag_list_get_date_time (const GstTagList * list, const gchar * tag,
  *
  * Free-function: gst_date_time_unref
  *
- * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
- *              given list or if it was #NULL.
- *
- * Since: 0.10.31
+ * Returns: %TRUE, if a value was copied, %FALSE if the tag didn't exist in the
+ *              given list or if it was %NULL.
  */
 gboolean
 gst_tag_list_get_date_time_index (const GstTagList * list,
@@ -1903,71 +1963,71 @@ gst_tag_list_get_date_time_index (const GstTagList * list,
 }
 
 /**
- * gst_tag_list_get_buffer:
+ * gst_tag_list_get_sample:
  * @list: a #GstTagList to get the tag from
  * @tag: tag to read out
- * @value: (out callee-allocates) (transfer full): address of a GstBuffer
+ * @sample: (out callee-allocates) (transfer full): address of a GstSample
  *     pointer variable to store the result into
  *
- * Copies the first buffer for the given tag in the taglist into the variable
- * pointed to by @value. Free the buffer with gst_buffer_unref() when it is
- * no longer needed.
+ * Copies the first sample for the given tag in the taglist into the variable
+ * pointed to by @sample. Free the sample with gst_sample_unref() when it is
+ * no longer needed. You can retrieve the buffer from the sample using
+ * gst_sample_get_buffer() and the associated caps (if any) with
+ * gst_sample_get_caps().
  *
- * Free-function: gst_buffer_unref
+ * Free-function: gst_sample_unref
  *
- * Returns: TRUE, if a buffer was copied, FALSE if the tag didn't exist in the
- *              given list or if it was #NULL.
- *
- * Since: 0.10.23
+ * Returns: %TRUE, if a sample was returned, %FALSE if the tag didn't exist in
+ *              the given list or if it was %NULL.
  */
 gboolean
-gst_tag_list_get_buffer (const GstTagList * list, const gchar * tag,
-    GstBuffer ** value)
+gst_tag_list_get_sample (const GstTagList * list, const gchar * tag,
+    GstSample ** sample)
 {
   GValue v = { 0, };
 
   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
   g_return_val_if_fail (tag != NULL, FALSE);
-  g_return_val_if_fail (value != NULL, FALSE);
+  g_return_val_if_fail (sample != NULL, FALSE);
 
   if (!gst_tag_list_copy_value (&v, list, tag))
     return FALSE;
-  *value = g_value_dup_boxed (&v);
+  *sample = g_value_dup_boxed (&v);
   g_value_unset (&v);
-  return (*value != NULL);
+  return (*sample != NULL);
 }
 
 /**
- * gst_tag_list_get_buffer_index:
+ * gst_tag_list_get_sample_index:
  * @list: a #GstTagList to get the tag from
  * @tag: tag to read out
  * @index: number of entry to read out
- * @value: (out callee-allocates) (transfer full): address of a GstBuffer
+ * @sample: (out callee-allocates) (transfer full): address of a GstSample
  *     pointer variable to store the result into
  *
- * Gets the buffer that is at the given index for the given tag in the given
- * list and copies it into the variable pointed to by @value. Free the buffer
- * with gst_buffer_unref() when it is no longer needed.
+ * Gets the sample that is at the given index for the given tag in the given
+ * list and copies it into the variable pointed to by @sample. Free the sample
+ * with gst_sample_unref() when it is no longer needed. You can retrieve the
+ * buffer from the sample using gst_sample_get_buffer() and the associated
+ * caps (if any) with gst_sample_get_caps().
  *
- * Free-function: gst_buffer_unref
+ * Free-function: gst_sample_unref
  *
- * Returns: TRUE, if a buffer was copied, FALSE if the tag didn't exist in the
- *              given list or if it was #NULL.
- *
- * Since: 0.10.23
+ * Returns: %TRUE, if a sample was copied, %FALSE if the tag didn't exist in the
+ *              given list or if it was %NULL.
  */
 gboolean
-gst_tag_list_get_buffer_index (const GstTagList * list,
-    const gchar * tag, guint index, GstBuffer ** value)
+gst_tag_list_get_sample_index (const GstTagList * list,
+    const gchar * tag, guint index, GstSample ** sample)
 {
   const GValue *v;
 
   g_return_val_if_fail (GST_IS_TAG_LIST (list), FALSE);
   g_return_val_if_fail (tag != NULL, FALSE);
-  g_return_val_if_fail (value != NULL, FALSE);
+  g_return_val_if_fail (sample != NULL, FALSE);
 
   if ((v = gst_tag_list_get_value_index (list, tag, index)) == NULL)
     return FALSE;
-  *value = g_value_dup_boxed (v);
-  return (*value != NULL);
+  *sample = g_value_dup_boxed (v);
+  return (*sample != NULL);
 }