From efe38286d10276ba2f316e10a9a04e062be651fc Mon Sep 17 00:00:00 2001
From: Anton Khirnov <anton@khirnov.net>
Date: Fri, 29 Mar 2024 08:50:26 +0100
Subject: [PATCH] lavu/opt: document underlying C types for enum AVOptionType

---
 libavutil/opt.h | 78 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 75 insertions(+), 3 deletions(-)

diff --git a/libavutil/opt.h b/libavutil/opt.h
index 07e27a9208..23bc495158 100644
--- a/libavutil/opt.h
+++ b/libavutil/opt.h
@@ -240,26 +240,98 @@
  * before the file is actually opened.
  */
 
+/**
+ * An option type determines:
+ * - for native access, the underlying C type of the field that an AVOption
+ *   refers to;
+ * - for foreign access, the semantics of accessing the option through this API,
+ *   e.g. which av_opt_get_*() and av_opt_set_*() functions can be called, or
+ *   what format will av_opt_get()/av_opt_set() expect/produce.
+ */
 enum AVOptionType{
+    /**
+     * Underlying C type is unsigned int.
+     */
     AV_OPT_TYPE_FLAGS = 1,
+    /**
+     * Underlying C type is int.
+     */
     AV_OPT_TYPE_INT,
+    /**
+     * Underlying C type is int64_t.
+     */
     AV_OPT_TYPE_INT64,
+    /**
+     * Underlying C type is double.
+     */
     AV_OPT_TYPE_DOUBLE,
+    /**
+     * Underlying C type is float.
+     */
     AV_OPT_TYPE_FLOAT,
+    /**
+     * Underlying C type is a uint8_t* that is either NULL or points to a C
+     * string allocated with the av_malloc() family of functions.
+     */
     AV_OPT_TYPE_STRING,
+    /**
+     * Underlying C type is AVRational.
+     */
     AV_OPT_TYPE_RATIONAL,
-    AV_OPT_TYPE_BINARY,  ///< offset must point to a pointer immediately followed by an int for the length
+    /**
+     * Underlying C type is a uint8_t* that is either NULL or points to an array
+     * allocated with the av_malloc() family of functions. The pointer is
+     * immediately followed by an int containing the array length in bytes.
+     */
+    AV_OPT_TYPE_BINARY,
+    /**
+     * Underlying C type is AVDictionary*.
+     */
     AV_OPT_TYPE_DICT,
+    /**
+     * Underlying C type is uint64_t.
+     */
     AV_OPT_TYPE_UINT64,
+    /**
+     * Special option type for declaring named constants. Does not correspond to
+     * an actual field in the object, offset must be 0.
+     */
     AV_OPT_TYPE_CONST,
-    AV_OPT_TYPE_IMAGE_SIZE, ///< offset must point to two consecutive ints
+    /**
+     * Underlying C type is two consecutive integers.
+     */
+    AV_OPT_TYPE_IMAGE_SIZE,
+    /**
+     * Underlying C type is enum AVPixelFormat.
+     */
     AV_OPT_TYPE_PIXEL_FMT,
+    /**
+     * Underlying C type is enum AVSampleFormat.
+     */
     AV_OPT_TYPE_SAMPLE_FMT,
-    AV_OPT_TYPE_VIDEO_RATE, ///< offset must point to AVRational
+    /**
+     * Underlying C type is AVRational.
+     */
+    AV_OPT_TYPE_VIDEO_RATE,
+    /**
+     * Underlying C type is int64_t.
+     */
     AV_OPT_TYPE_DURATION,
+    /**
+     * Underlying C type is uint8_t[4].
+     */
     AV_OPT_TYPE_COLOR,
+    /**
+     * Underlying C type is int.
+     */
     AV_OPT_TYPE_BOOL,
+    /**
+     * Underlying C type is AVChannelLayout.
+     */
     AV_OPT_TYPE_CHLAYOUT,
+    /**
+     * Underlying C type is unsigned int.
+     */
     AV_OPT_TYPE_UINT,
 
     /**