docs: specify possibility of a NULL return

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/3546>

diff --git a/subprojects/gstreamer/gst/gstbuffer.c b/subprojects/gstreamer/gst/gstbuffer.c
index cb84f47..fb2c787 100644 (file)
--- a/subprojects/gstreamer/gst/gstbuffer.c
+++ b/subprojects/gstreamer/gst/gstbuffer.c
@@ -746,7 +746,7 @@ _gst_buffer_copy (const GstBuffer * buffer)
  * Creates a copy of the given buffer. This will make a newly allocated
  * copy of the data the source buffer contains.
  *
- * Returns: (transfer full): a new copy of @buf.
+ * Returns: (transfer full) (nullable): a new copy of @buf if the copy succeeded, %NULL otherwise.
  *
  * Since: 1.6
  */
@@ -3009,7 +3009,7 @@ gst_clear_buffer (GstBuffer ** buf_ptr)
  * Check gst_buffer_copy_deep() if you want to force the data
  * to be copied to newly allocated memory.
  *
- * Returns: (transfer full): a new copy of @buf.
+ * Returns: (transfer full) (nullable): a new copy of @buf if the copy succeeded, %NULL otherwise.
  */
 GstBuffer *
 gst_buffer_copy (const GstBuffer * buf)

diff --git a/subprojects/gstreamer/gst/gstbuffer.h b/subprojects/gstreamer/gst/gstbuffer.h
index 74f21c3..6a8b84f 100644 (file)
--- a/subprojects/gstreamer/gst/gstbuffer.h
+++ b/subprojects/gstreamer/gst/gstbuffer.h
@@ -567,8 +567,8 @@ gboolean        gst_buffer_copy_into            (GstBuffer *dest, GstBuffer *src
  * 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
+ * Returns: (transfer full) (nullable): a writable buffer (which may or may not be the
+ *     same as @buf) or %NULL if copying is required but not possible.
  */
 #define         gst_buffer_make_writable(buf)   GST_BUFFER_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (buf)))
 

diff --git a/subprojects/gstreamer/gst/gstmemory.c b/subprojects/gstreamer/gst/gstmemory.c
index 0eaf208..10d724b 100644 (file)
--- a/subprojects/gstreamer/gst/gstmemory.c
+++ b/subprojects/gstreamer/gst/gstmemory.c
@@ -363,7 +363,7 @@ gst_memory_unmap (GstMemory * mem, GstMapInfo * info)
  * guaranteed to be writable. @size can be set to -1 to return a copy
  * from @offset to the end of the memory region.
  *
- * Returns: a new #GstMemory.
+ * Returns: (transfer full) (nullable): a new copy of @mem if the copy succeeded, %NULL otherwise.
  */
 GstMemory *
 gst_memory_copy (GstMemory * mem, gssize offset, gssize size)

diff --git a/subprojects/gstreamer/gst/gstmemory.h b/subprojects/gstreamer/gst/gstmemory.h
index 5da72d6..ee02d6d 100644 (file)
--- a/subprojects/gstreamer/gst/gstmemory.h
+++ b/subprojects/gstreamer/gst/gstmemory.h
@@ -359,6 +359,16 @@ void           gst_memory_resize       (GstMemory *mem, gssize offset, gsize siz
 #define        gst_memory_lock(m,f)        gst_mini_object_lock (GST_MINI_OBJECT_CAST (m), (f))
 #define        gst_memory_unlock(m,f)      gst_mini_object_unlock (GST_MINI_OBJECT_CAST (m), (f))
 #define        gst_memory_is_writable(m)   gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (m))
+/**
+ * gst_memory_make_writable:
+ * @m: (transfer full): a #GstMemory
+ *
+ * Returns a writable copy of @m. If the source memory is
+ * already writable, this will simply return the same memory.
+ *
+ * Returns: (transfer full) (nullable): a writable memory (which may or may not be the
+ *     same as @m) or %NULL if copying is required but not possible.
+ */
 #define        gst_memory_make_writable(m) GST_MEMORY_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (m)))
 
 /* retrieving data */

diff --git a/subprojects/gstreamer/gst/gstminiobject.c b/subprojects/gstreamer/gst/gstminiobject.c
index 3d1deab..18fdce0 100644 (file)
--- a/subprojects/gstreamer/gst/gstminiobject.c
+++ b/subprojects/gstreamer/gst/gstminiobject.c
@@ -423,8 +423,8 @@ gst_mini_object_is_writable (const GstMiniObject * mini_object)
  *
  * MT safe
  *
- * Returns: (transfer full): a mini-object (possibly the same pointer) that
- *     is writable.
+ * Returns: (transfer full) (nullable): a writable mini-object (which may or may not be
+ *     the same as @mini_object) or %NULL if copying is required but not possible.
  */
 GstMiniObject *
 gst_mini_object_make_writable (GstMiniObject * mini_object)