[FFmpeg-devel] [PATCH 04/11] avcodec/packet: add some documentation for AVPacketSideData

[Anton Khirnov]

Quoting James Almer (2023-09-27 15:12:35)
> Explaining what or who may use it, and in what scenarios.
> 
> Signed-off-by: James Almer <jamrial at gmail.com>
> ---
>  libavcodec/packet.h | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)
> 
> diff --git a/libavcodec/packet.h b/libavcodec/packet.h
> index 96fc0084d6..f88dad2b3c 100644
> --- a/libavcodec/packet.h
> +++ b/libavcodec/packet.h
> @@ -312,6 +312,21 @@ enum AVPacketSideDataType {
>  
>  #define AV_PKT_DATA_QUALITY_FACTOR AV_PKT_DATA_QUALITY_STATS //DEPRECATED
>  
> +/**
> + * This structure stores auxiliary
...information for decoding, presenting, or otherwise processing the
coded stream.

> It is typically exported by demuxers
> + * within @ref AVStream.codecpar.side_data "AVStream's codec parameters" or an
> + * @ref AVPacket.side_data "AVPacket" and then passed as input to decoders
> + * through the @ref AVCodecContext.coded_side_data "decoder context's side data"
> + * for initialization or through @ref AVPacket.side_data "AVPacket", or received
> + * as output from encoders within the @ref AVCodecContext.coded_side_data
> + * "encoder context's side data" or @ref AVPacket.side_data "AVPacket" and then
> + * passed to muxers through @ref AVStream.codecpar.side_data "AVStream's codec
> + * parameters" for initialization or through @ref AVPacket.side_data "AVPacket".

Long sentence is long. Consider the following:
* first state that it may be global or per-packet
* then describe the typical decoding path (demuxer->decoder, mention
  that it may be mapped to frame side data)
* then same for encoding

> + * Different modules may export or be provided different types of side data
                            ^^^^^^^^^^^^^^^^^^^^^
accept or export

Also, the doxy for AVCodecContext.coded_side_data,
AVCodecParameters.side_data and AVPacket.side_data should link to this
text, so it's actually discoverable for readers.

-- 
Anton Khirnov