From 654609ef158a33a99c9887a4660c23f135a2a350 Mon Sep 17 00:00:00 2001
From: Edward Hervey <edward@centricular.com>
Date: Mon, 10 Jul 2023 14:44:58 +0200
Subject: [PATCH] dsd: Fix documentation parameters

There were some inconsistencies between documentation and function signatures

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/5002>
---
 girs/GstAudio-1.0.gir                            | 16 +++++++++++-----
 .../gst-plugins-base/gst-libs/gst/audio/gstdsd.c |  2 +-
 .../gst-plugins-base/gst-libs/gst/audio/gstdsd.h |  2 +-
 .../gst-libs/gst/audio/gstdsdformat.c            |  4 ++--
 4 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/girs/GstAudio-1.0.gir b/girs/GstAudio-1.0.gir
index 368480ee7a..94e1db365f 100644
--- a/girs/GstAudio-1.0.gir
+++ b/girs/GstAudio-1.0.gir
@@ -9723,7 +9723,7 @@ in a more readable fashion.</doc>
         <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsdformat.h">32 DSD bits in 4 bytes, native endianness</doc>
       </member>
       <function name="from_string" c:identifier="gst_dsd_format_from_string" version="1.24">
-        <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsdformat.c">Convert the @format string to its #GstDsdFormat.</doc>
+        <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsdformat.c">Convert the DSD format string @str to its #GstDsdFormat.</doc>
         <source-position filename="../subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsdformat.h"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsdformat.c">the #GstDsdFormat for @format or GST_DSD_FORMAT_UNKNOWN when the
@@ -9732,6 +9732,7 @@ string is not a known format.</doc>
         </return-value>
         <parameters>
           <parameter name="str" transfer-ownership="none">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsdformat.c">a DSD format string</doc>
             <type name="utf8" c:type="const gchar*"/>
           </parameter>
         </parameters>
@@ -9947,8 +9948,11 @@ Note: This initializes @info first, no values are preserved.</doc>
             <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsd.c">the number of channels</doc>
             <type name="gint" c:type="gint"/>
           </parameter>
-          <parameter name="positions" transfer-ownership="none">
-            <type name="AudioChannelPosition" c:type="const GstAudioChannelPosition*"/>
+          <parameter name="positions" transfer-ownership="none" nullable="1" allow-none="1">
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsd.c">the channel positions</doc>
+            <array zero-terminated="0" c:type="const GstAudioChannelPosition*" fixed-size="64">
+              <type name="AudioChannelPosition" c:type="GstAudioChannelPosition"/>
+            </array>
           </parameter>
         </parameters>
       </method>
@@ -11580,13 +11584,14 @@ are ignored.</doc>
           <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsd.c">Number of channels (must be at least 1)</doc>
           <type name="gint" c:type="gint"/>
         </parameter>
-        <parameter name="reverse_bytes" transfer-ownership="none">
+        <parameter name="reverse_byte_bits" transfer-ownership="none">
+          <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsd.c">If TRUE, reverse the bits in each DSD byte</doc>
           <type name="gboolean" c:type="gboolean"/>
         </parameter>
       </parameters>
     </function>
     <function name="dsd_format_from_string" c:identifier="gst_dsd_format_from_string" moved-to="DsdFormat.from_string" version="1.24">
-      <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsdformat.c">Convert the @format string to its #GstDsdFormat.</doc>
+      <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsdformat.c">Convert the DSD format string @str to its #GstDsdFormat.</doc>
       <source-position filename="../subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsdformat.h"/>
       <return-value transfer-ownership="none">
         <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsdformat.c">the #GstDsdFormat for @format or GST_DSD_FORMAT_UNKNOWN when the
@@ -11595,6 +11600,7 @@ string is not a known format.</doc>
       </return-value>
       <parameters>
         <parameter name="str" transfer-ownership="none">
+          <doc xml:space="preserve" filename="../subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsdformat.c">a DSD format string</doc>
           <type name="utf8" c:type="const gchar*"/>
         </parameter>
       </parameters>
diff --git a/subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsd.c b/subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsd.c
index 62da97ed84..9b17509006 100644
--- a/subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsd.c
+++ b/subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsd.c
@@ -345,7 +345,7 @@ gst_dsd_info_init (GstDsdInfo * info)
  * @format: the format
  * @rate: the DSD rate
  * @channels: the number of channels
- * @position: (array fixed-size=64) (nullable): the channel positions
+ * @positions: (array fixed-size=64) (nullable): the channel positions
  *
  * Set the default info for the DSD info of @format and @rate and @channels.
  *
diff --git a/subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsd.h b/subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsd.h
index 4947c32db1..c59bf433a0 100644
--- a/subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsd.h
+++ b/subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsd.h
@@ -311,7 +311,7 @@ void          gst_dsd_convert            (const guint8 *input_data,
                                           const gsize *output_plane_offsets,
                                           gsize num_dsd_bytes, 
                                           gint num_channels, 
-                                          gboolean reverse_bytes);
+                                          gboolean reverse_byte_bits);
 
 /**
  * gst_dsd_format_is_le:
diff --git a/subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsdformat.c b/subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsdformat.c
index 8c657b5695..77ec7e5b14 100644
--- a/subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsdformat.c
+++ b/subprojects/gst-plugins-base/gst-libs/gst/audio/gstdsdformat.c
@@ -25,9 +25,9 @@
 
 /**
  * gst_dsd_format_from_string:
- * @format: a format string
+ * @str: a DSD format string
  *
- * Convert the @format string to its #GstDsdFormat.
+ * Convert the DSD format string @str to its #GstDsdFormat.
  *
  * Returns: the #GstDsdFormat for @format or GST_DSD_FORMAT_UNKNOWN when the
  * string is not a known format.