From 73338aa1ae3cb97bfe9df1dcde677a1086578dd8 Mon Sep 17 00:00:00 2001
From: Nicolas Dufresne <nicolas.dufresne@collabora.com>
Date: Fri, 1 Dec 2023 12:10:36 -0500
Subject: [PATCH] doc: baseparse: Clarify consumed vs output size

When we finish a frame, we pass a size which semantic can easily be confused.
Improve the documentation to clarify that the parameter size is the amount of
input data being consumed and, if set, the output_buffer size can differ.

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/5754>
---
 girs/GstBase-1.0.gir                               | 7 +++++--
 subprojects/gstreamer/libs/gst/base/gstbaseparse.c | 7 +++++--
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/girs/GstBase-1.0.gir b/girs/GstBase-1.0.gir
index 4ed31b846a..916e787fd5 100644
--- a/girs/GstBase-1.0.gir
+++ b/girs/GstBase-1.0.gir
@@ -3161,10 +3161,13 @@ is emptied or chain returns with error.</doc>
         </parameters>
       </method>
       <method name="finish_frame" c:identifier="gst_base_parse_finish_frame">
-        <doc xml:space="preserve" filename="../subprojects/gstreamer/libs/gst/base/gstbaseparse.c">Collects parsed data and pushes this downstream.
+        <doc xml:space="preserve" filename="../subprojects/gstreamer/libs/gst/base/gstbaseparse.c">Collects parsed data and pushes it downstream.
 Source pad caps must be set when this is called.
 
-If @frame's out_buffer is set, that will be used as subsequent frame data.
+If @frame's out_buffer is set, that will be used as subsequent frame data,
+and @size amount will be flushed from the input data. The output_buffer size
+can differ from the consumed size indicated by @size.
+
 Otherwise, @size samples will be taken from the input and used for output,
 and the output's metadata (timestamps etc) will be taken as (optionally)
 set by the subclass on @frame's (input) buffer (which is otherwise
diff --git a/subprojects/gstreamer/libs/gst/base/gstbaseparse.c b/subprojects/gstreamer/libs/gst/base/gstbaseparse.c
index 92553ea134..422e489c32 100644
--- a/subprojects/gstreamer/libs/gst/base/gstbaseparse.c
+++ b/subprojects/gstreamer/libs/gst/base/gstbaseparse.c
@@ -2682,10 +2682,13 @@ no_caps:
  * @frame: a #GstBaseParseFrame
  * @size: consumed input data represented by frame
  *
- * Collects parsed data and pushes this downstream.
+ * Collects parsed data and pushes it downstream.
  * Source pad caps must be set when this is called.
  *
- * If @frame's out_buffer is set, that will be used as subsequent frame data.
+ * If @frame's out_buffer is set, that will be used as subsequent frame data,
+ * and @size amount will be flushed from the input data. The output_buffer size
+ * can differ from the consumed size indicated by @size.
+ *
  * Otherwise, @size samples will be taken from the input and used for output,
  * and the output's metadata (timestamps etc) will be taken as (optionally)
  * set by the subclass on @frame's (input) buffer (which is otherwise