From 183c59b4738c20e65ffe63b456c6f7bb0d5caf5b Mon Sep 17 00:00:00 2001
From: Anton Khirnov <anton@khirnov.net>
Date: Thu, 5 Dec 2024 10:52:03 +0100
Subject: [PATCH] lavc: improve AVCodecContext.extradata/subtitle_header
 documentation

Mention they are always owned and freed by the codec, except when using
deprecated avcodec_close().

Reported-By: DEATH on IRC
---
 libavcodec/avcodec.h | 40 ++++++++++++++++++++++++++++------------
 1 file changed, 28 insertions(+), 12 deletions(-)

diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 77ca8dee1f..12e6e8749f 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -515,16 +515,24 @@ typedef struct AVCodecContext {
     int flags2;
 
     /**
-     * some codecs need / can use extradata like Huffman tables.
-     * MJPEG: Huffman tables
-     * rv10: additional flags
-     * MPEG-4: global headers (they can be in the bitstream or here)
-     * The allocated memory should be AV_INPUT_BUFFER_PADDING_SIZE bytes larger
-     * than extradata_size to avoid problems if it is read with the bitstream reader.
-     * The bytewise contents of extradata must not depend on the architecture or CPU endianness.
-     * Must be allocated with the av_malloc() family of functions.
-     * - encoding: Set/allocated/freed by libavcodec.
-     * - decoding: Set/allocated/freed by user.
+     * Out-of-band global headers that may be used by some codecs.
+     *
+     * - decoding: Should be set by the caller when available (typically from a
+     *   demuxer) before opening the decoder; some decoders require this to be
+     *   set and will fail to initialize otherwise.
+     *
+     *   The array must be allocated with the av_malloc() family of functions;
+     *   allocated size must be at least AV_INPUT_BUFFER_PADDING_SIZE bytes
+     *   larger than extradata_size.
+     *
+     * - encoding: May be set by the encoder in avcodec_open2() (possibly
+     *   depending on whether the AV_CODEC_FLAG_GLOBAL_HEADER flag is set).
+     *
+     * After being set, the array is owned by the codec and freed in
+     * avcodec_free_context().
+     *
+     * @warning the deprecated avcodec_close() function DOES NOT free this array
+     * for decoding, it must be freed manually by the caller.
      */
     uint8_t *extradata;
     int extradata_size;
@@ -1895,8 +1903,16 @@ typedef struct AVCodecContext {
      * For SUBTITLE_ASS subtitle type, it should contain the whole ASS
      * [Script Info] and [V4+ Styles] section, plus the [Events] line and
      * the Format line following. It shouldn't include any Dialogue line.
-     * - encoding: Set/allocated/freed by user (before avcodec_open2())
-     * - decoding: Set/allocated/freed by libavcodec (by avcodec_open2())
+     *
+     * - encoding: May be set by the caller before avcodec_open2() to an array
+     *   allocated with the av_malloc() family of functions.
+     * - decoding: May be set by libavcodec in avcodec_open2().
+     *
+     * After being set, the array is owned by the codec and freed in
+     * avcodec_free_context().
+     *
+     * @warning the deprecated avcodec_close() function DOES NOT free this array
+     * for encoding, it must be freed manually by the caller.
      */
     int subtitle_header_size;
     uint8_t *subtitle_header;