From 2080aff70cd79c01d176f404a0a8862497eb9b0d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Alicia=20Boya=20Garc=C3=ADa?= <aboya@igalia.com>
Date: Mon, 29 Jan 2018 19:46:26 +0100
Subject: [PATCH] adapter: Improve documentation for gst_adapter_available()

When I first read the documentation of gst_adapter_available() and
gst_adapter_available_fast() I got quite confused as it seemed that
both performed the same purpose but one was slower than the other.

I shared it with other people and found they also arrived at the same
wrong conclusion.

Hopefully this patch will make the actual purpose clearer.

Fixes https://gitlab.freedesktop.org/gstreamer/gst-docs/-/issues/12

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/7859>
---
 girs/GstBase-1.0.gir                             | 13 ++++++++++---
 subprojects/gstreamer/libs/gst/base/gstadapter.c | 11 +++++++++--
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/girs/GstBase-1.0.gir b/girs/GstBase-1.0.gir
index 5bf37c7d33..bcdf9a5391 100644
--- a/girs/GstBase-1.0.gir
+++ b/girs/GstBase-1.0.gir
@@ -207,7 +207,11 @@ buffer pushed in it.</doc>
       <method name="available" c:identifier="gst_adapter_available">
         <doc xml:space="preserve" filename="../subprojects/gstreamer/libs/gst/base/gstadapter.c">Gets the maximum amount of bytes available, that is it returns the maximum
 value that can be supplied to gst_adapter_map() without that function
-returning %NULL.</doc>
+returning %NULL.
+
+Calling gst_adapter_map() with the amount of bytes returned by this function
+may require expensive operations (like copying the data into a temporary
+buffer) in some cases.</doc>
         <source-position filename="../subprojects/gstreamer/libs/gst/base/gstadapter.h"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve" filename="../subprojects/gstreamer/libs/gst/base/gstadapter.c">number of bytes available in @adapter</doc>
@@ -221,8 +225,11 @@ returning %NULL.</doc>
         </parameters>
       </method>
       <method name="available_fast" c:identifier="gst_adapter_available_fast">
-        <doc xml:space="preserve" filename="../subprojects/gstreamer/libs/gst/base/gstadapter.c">Gets the maximum number of bytes that are immediately available without
-requiring any expensive operations (like copying the data into a
+        <doc xml:space="preserve" filename="../subprojects/gstreamer/libs/gst/base/gstadapter.c">Gets the maximum number of bytes that can be retrieved in a single map
+operation without merging buffers.
+
+Calling gst_adapter_map() with the amount of bytes returned by this function
+will never require any expensive operations (like copying the data into a
 temporary buffer).</doc>
         <source-position filename="../subprojects/gstreamer/libs/gst/base/gstadapter.h"/>
         <return-value transfer-ownership="none">
diff --git a/subprojects/gstreamer/libs/gst/base/gstadapter.c b/subprojects/gstreamer/libs/gst/base/gstadapter.c
index 5886ee932e..9aa51b01a4 100644
--- a/subprojects/gstreamer/libs/gst/base/gstadapter.c
+++ b/subprojects/gstreamer/libs/gst/base/gstadapter.c
@@ -1314,6 +1314,10 @@ gst_adapter_get_buffer_list (GstAdapter * adapter, gsize nbytes)
  * value that can be supplied to gst_adapter_map() without that function
  * returning %NULL.
  *
+ * Calling gst_adapter_map() with the amount of bytes returned by this function
+ * may require expensive operations (like copying the data into a temporary
+ * buffer) in some cases.
+ *
  * Returns: number of bytes available in @adapter
  */
 gsize
@@ -1328,8 +1332,11 @@ gst_adapter_available (GstAdapter * adapter)
  * gst_adapter_available_fast:
  * @adapter: a #GstAdapter
  *
- * Gets the maximum number of bytes that are immediately available without
- * requiring any expensive operations (like copying the data into a
+ * Gets the maximum number of bytes that can be retrieved in a single map
+ * operation without merging buffers.
+ *
+ * Calling gst_adapter_map() with the amount of bytes returned by this function
+ * will never require any expensive operations (like copying the data into a
  * temporary buffer).
  *
  * Returns: number of bytes that are available in @adapter without expensive