[gst-cvs] gstreamer: docs: improve API reference for gst_caps_get_structure()

[Tim Mueller]

Module: gstreamer
Branch: master
Commit: 01166ec0cd11e91a463c3aed2366a1fb0ecbf578
URL:    http://cgit.freedesktop.org/gstreamer/gstreamer/commit/?id=01166ec0cd11e91a463c3aed2366a1fb0ecbf578

Author: Tim-Philipp Müller <tim.muller at collabora.co.uk>
Date:   Fri Apr  3 11:19:42 2009 +0100

docs: improve API reference for gst_caps_get_structure()

---

 gst/gstcaps.c |    9 ++++++++-
 1 files changed, 8 insertions(+), 1 deletions(-)

diff --git a/gst/gstcaps.c b/gst/gstcaps.c
index b3755f2..89ad6aa 100644
--- 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
- * #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
  */