[FFmpeg-devel] [PATCH 2/2] all: harmonise "{Decoding, Encoding, Audio, Video}:" comments

[Stefano Sabatini]

On date Thursday 2024-02-29 16:23:07 +0000, Andrew Sayers wrote:

> There seems to be a convention for documenting meanings:
> 
>     /**
>      * Encoding: (meaning in encoding context)
>      * Decoding: (meaning in decoding context)
>      */
> 
> At a glance, these are confusingly similar to ownership comments.
> They are also rendered by doxygen as long, hard-to-read paragraphs.

I still don't understand what you mean by "ownership" and "meaning"
and their difference.

To me they look like the same thing, i.e. they define the semantics
depending on the operation context (encoding/decoding). In addition to
this, there might be a difference releated to the media content. To
distinguish the two, I'd say "operational" and "media" context.

> Reformat these comments to be more visually distinct and readable.
> ---
>  libavcodec/avcodec.h   | 19 +++++++++++++------
>  libavformat/avformat.h | 22 +++++++++++++++-------
>  2 files changed, 28 insertions(+), 13 deletions(-)
> 
> diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
> index 43859251cc..e2193f1d00 100644
> --- a/libavcodec/avcodec.h
> +++ b/libavcodec/avcodec.h
> @@ -586,16 +586,23 @@ typedef struct AVCodecContext {
>      /**
>       * Codec delay.
>       *
> -     * Encoding: Number of frames delay there will be from the encoder input to
> -     *           the decoder output. (we assume the decoder matches the spec)
> -     * Decoding: Number of frames delay in addition to what a standard decoder
> -     *           as specified in the spec would produce.
> +     * *Encoding:*
> +     *
> +     *   Number of frames delay there will be from the encoder input to
> +     *   the decoder output. (we assume the decoder matches the spec).
> +     *
> +     * *Decoding:*
> +     *
> +     *   Number of frames delay in addition to what a standard decoder
> +     *   as specified in the spec would produce.
> +     *
> +     * *Video:*
>       *
> -     * Video:
>       *   Number of frames the decoded output will be delayed relative to the
>       *   encoded input.
>       *
> -     * Audio:
> +     * *Audio:*
> +     *
>       *   For encoding, this field is unused (see initial_padding).
>       *
>       *   For decoding, this is the number of samples the decoder needs to
> diff --git a/libavformat/avformat.h b/libavformat/avformat.h
> index 35b7f78ec7..be97947bd1 100644
> --- a/libavformat/avformat.h
> +++ b/libavformat/avformat.h
> @@ -882,19 +882,27 @@ typedef struct AVStream {
>      AVRational time_base;
>  
>      /**
> -     * Decoding: pts of the first frame of the stream in presentation order, in stream time base.
> -     * Only set this if you are absolutely 100% sure that the value you set
> -     * it to really is the pts of the first frame.
> -     * This may be undefined (AV_NOPTS_VALUE).
> +     * *Decoding:*
> +     *
> +     *   pts of the first frame of the stream in presentation order, in stream time base.
> +     *
> +     *   Only set this if you are absolutely 100% sure that the value you set
> +     *   it to really is the pts of the first frame.
> +     *
> +     *   This may be undefined (AV_NOPTS_VALUE).
> +     *

This conventions seems at odd with the prevoius patch, where you was
preferring the - decoding/- encoding style.

[...]