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@ffmpeg.org
> https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
>
> To unsubscribe, visit link above, or email
> ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".
