docs: Improve gst_buffer_get_meta() to clear up confusion

I was confused by the existence of `gst_buffer_get_meta` as it suggested
to me that you should only attach one of any type of GstMeta to a buffer.
It's perfectly fine to attach multiple from a single API so I'm
documenting that here.

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

diff --git a/gst/gstbuffer.c b/gst/gstbuffer.c
index eb7077a..720da8b 100644 (file)
--- a/gst/gstbuffer.c
+++ b/gst/gstbuffer.c
@@ -1935,8 +1935,11 @@ gst_buffer_append_region (GstBuffer * buf1, GstBuffer * buf2, gssize offset,
  * @buffer: a #GstBuffer
  * @api: the #GType of an API
  *
- * Get the metadata for @api on buffer. When there is no such
- * metadata, %NULL is returned.
+ * Get the metadata for @api on buffer. When there is no such metadata, %NULL is
+ * returned. If multiple metadata with the given @api are attached to this
+ * buffer only the first one is returned.  To handle multiple metadata with a
+ * given API use gst_buffer_iterate_meta() or gst_buffer_foreach_meta() instead
+ * and check the meta->info.api member for the API type.
  *
  * Returns: (transfer none) (nullable): the metadata for @api on
  * @buffer.