docs: improve API reference for gst_caps_get_structure()

diff --git a/gst/gstcaps.c b/gst/gstcaps.c
index b3755f2..89ad6aa 100644 (file)
--- a/gst/gstcaps.c
+++ b/gst/gstcaps.c
@@ -793,7 +793,14 @@ gst_caps_get_size (const GstCaps * caps)
  * WARNING: This function takes a const GstCaps *, but returns a
  * non-const GstStructure *.  This is for programming convenience --
  * the caller should be aware that structures inside a constant
  * WARNING: This function takes a const GstCaps *, but returns a
  * non-const GstStructure *.  This is for programming convenience --
  * the caller should be aware that structures inside a constant

- * #GstCaps should not be modified.
+ * #GstCaps should not be modified. However, if you know the caps
+ * are writable, either because you have just copied them or made
+ * them writable with gst_caps_make_writable(), you may modify the
+ * structure returned in the usual way, e.g. with functions like
+ * gst_structure_set_simple().
+ *
+ * You do not need to free or unref the structure returned, it
+ * belongs to the #GstCaps.

  *
  * Returns: a pointer to the #GstStructure corresponding to @index
  */
  *
  * Returns: a pointer to the #GstStructure corresponding to @index
  */