From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org [79.124.17.100]) by master.gitmailbox.com (Postfix) with ESMTP id 59D9B453F5 for ; Sat, 28 Jan 2023 14:47:13 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 2C84468BB11; Sat, 28 Jan 2023 16:47:12 +0200 (EET) Received: from mail-ej1-f51.google.com (mail-ej1-f51.google.com [209.85.218.51]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id D20F268BB11 for ; Sat, 28 Jan 2023 16:47:05 +0200 (EET) Received: by mail-ej1-f51.google.com with SMTP id hx15so1240154ejc.11 for ; Sat, 28 Jan 2023 06:47:05 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=66USIIA5BfyCbQ8/KZ8VWbEEQHQ469AKGDdSkEb038g=; b=ZC2tL7Ubfpo+mSTXb8iriL+HYy9NZam1n1hSZmdyx9w3UqSRVonoXIbkb5sIYT3vU7 Dz2GIehKEYMyUNJ+bfWQR8z02hVD3+kfBnRlWWozHfbcLURLOhwekmfkBxs8OQ8B7t31 bRIzPo6ojoM+PMX8+biL37Mq2mbFEiF9QP3WS1sPwl4UEURRLphneB8zpdlckBDWGHAH WGDxrJQiyHaOGPKF6Qfqxyefk9ulv0kNPMlmJ66StTCsXfgNZSafcyDVDC/yKqXaB9KJ qUEMYipqeo1o3lRGeO3VwuHzSiqdl4FZc7YWMBtxnrfxM9uYcCItvdrxpgFaAi/dfNPO 1qwg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=66USIIA5BfyCbQ8/KZ8VWbEEQHQ469AKGDdSkEb038g=; b=p7Sp+olNtA2GMFaLmUsCMu9+fYrnDGvAABYei6FAhJpJIgv5+1/fktL8qEEJcBU7BG txDu2DgKTvkhYjgsRku+LmTNXCxubGmQKyxCqE8DjAwprA9BuVFuVAIUAS+o6DXZdfPF 8hdNxNOntMG+cu38WqtxyzsaPflLF3QxNIiKkS29hq7GhCI2tIAQfH8qLTSWQdo5XnnN Iq+c6d0uk6gR4IoK8j4W8zIdyFsoPG8vk48f6cdPb5Qd2PGH68TIRz8yPNhChY42g7gA oel6NZMgExznARbwTGBdAKD3HWF0d9c25MRiuLVQqEsYduJfrZ3PdcDlYigrSKlvzFGN 7RdQ== X-Gm-Message-State: AO0yUKVTtga7tdlpeIXoefIkP4D2VORkODoiPAk9t/+vejYUb9WSKarb UAsAGvsAVSAxXGT16kpfPInXesEh5aPGLQ== X-Google-Smtp-Source: AK7set9crPSOl5ssV0yej/HgmSm7mIW4LmVNzpZQbbR8fMk0LCBrNO67TdUQPcF5FC6waNM/KGDzkQ== X-Received: by 2002:a17:907:74d:b0:878:82c7:f5dc with SMTP id xc13-20020a170907074d00b0087882c7f5dcmr10197103ejb.56.1674917225219; Sat, 28 Jan 2023 06:47:05 -0800 (PST) Received: from [192.168.1.104] (84-112-104-25.cable.dynamic.surfer.at. [84.112.104.25]) by smtp.gmail.com with ESMTPSA id fm19-20020a1709072ad300b007c10d47e748sm3904824ejc.36.2023.01.28.06.47.04 for (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Sat, 28 Jan 2023 06:47:04 -0800 (PST) From: Marvin Scholz To: FFmpeg development discussions and patches Date: Sat, 28 Jan 2023 15:47:03 +0100 X-Mailer: MailMate (1.14r5936) Message-ID: <0F1AD93D-DEEB-4F7B-98B6-E2B63C6C7CEF@gmail.com> In-Reply-To: <167491222759.4503.5349780751227464325@lain.khirnov.net> References: <20230125165537.5371-1-anton@khirnov.net> <167491222759.4503.5349780751227464325@lain.khirnov.net> MIME-Version: 1.0 Subject: Re: [FFmpeg-devel] [PATCH 01/19] lavc/avcodec: improve enc/dec API doxy X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: 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-request@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-request@ffmpeg.org with subject "unsubscribe".