buffer: flesh out docs for gst_buffer_make_writable() a little

There is a similar explanation in gst_caps_make_writable, but the existing
documentation can be misleading since it does not define what 'is already
writable' means.

Also note when this function is meant to be used.

diff --git a/gst/gstbuffer.h b/gst/gstbuffer.h
index 4343b6a..59a1f39 100644 (file)
--- a/gst/gstbuffer.h
+++ b/gst/gstbuffer.h
@@ -462,9 +462,24 @@ gboolean        gst_buffer_copy_into            (GstBuffer *dest, GstBuffer *src
  * gst_buffer_make_writable:
  * @buf: (transfer full): a #GstBuffer
  *
- * Makes a writable buffer from the given buffer. If the source buffer is
- * already writable, this will simply return the same buffer. A copy will
- * otherwise be made using gst_buffer_copy().
+ * Returns a writable copy of @buf. If the source buffer is
+ * already writable, this will simply return the same buffer.
+ *
+ * Use this function to ensure that a buffer can be safely modified before
+ * making changes to it, including changing the metadata such as PTS/DTS.
+ *
+ * If the reference count of the source buffer @buf is exactly one, the caller
+ * is the sole owner and this function will return the buffer object unchanged.
+ *
+ * If there is more than one reference on the object, a copy will be made using
+ * gst_buffer_copy(). The passed-in @buf will be unreffed in that case, and the
+ * caller will now own a reference to the new returned buffer object. Note
+ * that this just copies the buffer structure itself, the underlying memory is
+ * not copied if it can be shared amongst multiple buffers.
+ *
+ * In short, this function unrefs the buf in the argument and refs the buffer
+ * that it returns. Don't access the argument after calling this function unless
+ * you have an additional reference to it.
  *
  * Returns: (transfer full): a writable buffer which may or may not be the
  *     same as @buf