[FFmpeg-devel] [PATCH 01/19] lavc/avcodec: improve enc/dec API doxy

[Marvin Scholz]

On 28 Jan 2023, at 14:23, Anton Khirnov wrote:

> Quoting Marvin Scholz (2023-01-28 12:37:42)
>>
>>
>> On 25 Jan 2023, at 17:55, Anton Khirnov wrote:
>>
>>> Change return value descriptions into proper lists.
>>> ---
>>>  libavcodec/avcodec.h | 81 +++++++++++++++++++++++---------------------
>>>  1 file changed, 42 insertions(+), 39 deletions(-)
>>>
>>> diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
>>> index 0ac581d660..f3ca41f126 100644
>>> --- a/libavcodec/avcodec.h
>>> +++ b/libavcodec/avcodec.h
>>> @@ -2605,17 +2605,18 @@ int avcodec_decode_subtitle2(AVCodecContext *avctx, AVSubtitle *sub,
>>>   *                  still has frames buffered, it will return them after sending
>>>   *                  a flush packet.
>>>   *
>>> - * @return 0 on success, otherwise negative error code:
>>> - *      AVERROR(EAGAIN):   input is not accepted in the current state - user
>>> - *                         must read output with avcodec_receive_frame() (once
>>> - *                         all output is read, the packet should be resent, and
>>> - *                         the call will not fail with EAGAIN).
>>> - *      AVERROR_EOF:       the decoder has been flushed, and no new packets can
>>> - *                         be sent to it (also returned if more than 1 flush
>>> - *                         packet is sent)
>>> - *      AVERROR(EINVAL):   codec not opened, it is an encoder, or requires flush
>>> - *      AVERROR(ENOMEM):   failed to add packet to internal queue, or similar
>>> - *      other errors: legitimate decoding errors
>>> + * @return
>>> + * - 0:                 success
>>> + * - AVERROR(EAGAIN):   input is not accepted in the current state - user must
>>> + *                      read output with avcodec_receive_frame() (once all
>>> + *                      output is read, the packet should be resent, and the
>>> + *                      call will not fail with EAGAIN).
>>> + * - AVERROR_EOF:       the decoder has been flushed, and no new packets can be
>>> + *                      sent to it (also returned if more than 1 flush packet is
>>> + *                      sent)
>>> + * - AVERROR(EINVAL):   codec not opened, it is an encoder, or requires flush
>>> + * - AVERROR(ENOMEM):   failed to add packet to internal queue, or similar
>>> + * - other errors:      legitimate decoding errors
>>>   */
>>
>> Wouldn't @retval work better for such return value documentation?
>
> I don't know, how is it better?
>

It should produce a more consistent output like in other places that use retval and is
semantically the more correct choice here.

Currently the documentation of possible return values is a bit all over the place with
some using lists, others just explain the values in a sentence, other places use retval.

IMO we should consistently try to use retval where it makes sense.

> -- 
> Anton Khirnov
> _______________________________________________
> ffmpeg-devel mailing list
> ffmpeg-devel at ffmpeg.org
> https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
>
> To unsubscribe, visit link above, or email
> ffmpeg-devel-request at ffmpeg.org with subject "unsubscribe".