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

[Marvin Scholz]

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?

>  int avcodec_send_packet(AVCodecContext *avctx, const AVPacket *avpkt);
>
> @@ -2630,17 +2631,17 @@ int avcodec_send_packet(AVCodecContext *avctx, const AVPacket *avpkt);
>   *              av_frame_unref(frame) before doing anything else.
>   *
>   * @return
> - *      0:                 success, a frame was returned
> - *      AVERROR(EAGAIN):   output is not available in this state - user must try
> - *                         to send new input
> - *      AVERROR_EOF:       the codec has been fully flushed, and there will be
> - *                         no more output frames
> - *      AVERROR(EINVAL):   codec not opened, or it is an encoder without
> - *                         the AV_CODEC_FLAG_RECON_FRAME flag enabled
> - *      AVERROR_INPUT_CHANGED:   current decoded frame has changed parameters
> - *                               with respect to first decoded frame. Applicable
> - *                               when flag AV_CODEC_FLAG_DROPCHANGED is set.
> - *      other negative values: legitimate decoding errors
> + * - 0:                     success, a frame was returned
> + * - AVERROR(EAGAIN):       output is not available in this state - user must
> + *                          try to send new input
> + * - AVERROR_EOF:           the codec has been fully flushed, and there will be
> + *                          no more output frames
> + * - AVERROR(EINVAL):       codec not opened, or it is an encoder without the
> + *                          AV_CODEC_FLAG_RECON_FRAME flag enabled
> + * - AVERROR_INPUT_CHANGED: current decoded frame has changed parameters with
> + *                          respect to first decoded frame. Applicable when flag
> + *                          AV_CODEC_FLAG_DROPCHANGED is set.
> + * - other negative values: legitimate decoding errors
>   */
>  int avcodec_receive_frame(AVCodecContext *avctx, AVFrame *frame);
>
> @@ -2667,16 +2668,17 @@ int avcodec_receive_frame(AVCodecContext *avctx, AVFrame *frame);
>   *                  If it is not set, frame->nb_samples must be equal to
>   *                  avctx->frame_size for all frames except the last.
>   *                  The final frame may be smaller than avctx->frame_size.
> - * @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_packet() (once
> - *                         all output is read, the packet should be resent, and
> - *                         the call will not fail with EAGAIN).
> - *      AVERROR_EOF:       the encoder has been flushed, and no new frames can
> - *                         be sent to it
> - *      AVERROR(EINVAL):   codec not opened, it is a decoder, or requires flush
> - *      AVERROR(ENOMEM):   failed to add packet to internal queue, or similar
> - *      other errors: legitimate encoding errors
> + * @return
> + * - 0:                 success
> + * - AVERROR(EAGAIN):   input is not accepted in the current state - user must
> + *                      read output with avcodec_receive_packet() (once all
> + *                      output is read, the packet should be resent, and the
> + *                      call will not fail with EAGAIN).
> + * - AVERROR_EOF:       the encoder has been flushed, and no new frames can
> + *                      be sent to it
> + * - AVERROR(EINVAL):   codec not opened, it is a decoder, or requires flush
> + * - AVERROR(ENOMEM):   failed to add packet to internal queue, or similar
> + * - other errors:      legitimate encoding errors
>   */
>  int avcodec_send_frame(AVCodecContext *avctx, const AVFrame *frame);
>
> @@ -2687,13 +2689,14 @@ int avcodec_send_frame(AVCodecContext *avctx, const AVFrame *frame);
>   * @param avpkt This will be set to a reference-counted packet allocated by the
>   *              encoder. Note that the function will always call
>   *              av_packet_unref(avpkt) before doing anything else.
> - * @return 0 on success, otherwise negative error code:
> - *      AVERROR(EAGAIN):   output is not available in the current state - user
> - *                         must try to send input
> - *      AVERROR_EOF:       the encoder has been fully flushed, and there will be
> - *                         no more output packets
> - *      AVERROR(EINVAL):   codec not opened, or it is a decoder
> - *      other errors: legitimate encoding errors
> + * @return
> + * - 0:                 success
> + * - AVERROR(EAGAIN):   output is not available in the current state - user must
> + *                      try to send input
> + * - AVERROR_EOF:       the encoder has been fully flushed, and there will be no
> + *                      more output packets
> + * - AVERROR(EINVAL):   codec not opened, or it is a decoder
> + * - other errors:      legitimate encoding errors
>   */
>  int avcodec_receive_packet(AVCodecContext *avctx, AVPacket *avpkt);
>
> -- 
> 2.35.1
>
> _______________________________________________
> 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".