From patchwork Thu Feb 29 16:23:06 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 46655 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:a919:b0:19e:cdac:8cce with SMTP id cd25csp707648pzb; Thu, 29 Feb 2024 08:24:47 -0800 (PST) X-Forwarded-Encrypted: i=2; AJvYcCWf5YpTdygaC90tmIe0mPinXxj8UGBoHzkHTmHXCDNvRu9m0LYsAs76ojOpKDYp57dpCMU7Q+WoCTvxk3vXgpEuoXw8JfSqKGD11w== X-Google-Smtp-Source: AGHT+IHBzF35R8d0Ol3v8E2Vb3F4v4D8y733sELIfaUhr8ziyUbbr30DHLJrYi+6c2l21dIlP5Ur X-Received: by 2002:a17:906:3bd2:b0:a43:8468:ac0a with SMTP id v18-20020a1709063bd200b00a438468ac0amr2013295ejf.71.1709223887276; Thu, 29 Feb 2024 08:24:47 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1709223887; cv=none; d=google.com; s=arc-20160816; b=0A1+3MxgtlA1V29jDI8hPcZ3hbPSRK6ikoGP/Em+Y6kgpWytVmZGkgoMJCvFRKX7/L nAr+yj6Ojs3QeTTvyDHBQFABjYE6t2xvSkWFU7hwmXi3GVpEDUoXuEUL2Xl9oP4qGAeU d2MkBwktgf8jKaXVQVhPN0AkC/qA0Yhz+OouW/d3HSKkSjQYdJIWwMZTV3gOHs8gNFnw o+ukajvuF4bD1buv2j+5QDunsqBU1kL34EzCF8w2QrOIjfGc4umhemtye+2JTqJKXsQJ AlWtxf6VXrKBfia9y4WCDtxfNo5lQhhM2M82YfVb0BlIPcO++1dOUTVxKFWp2zKRksso Nw/w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:cc:reply-to :list-subscribe:list-help:list-post:list-archive:list-unsubscribe :list-id:precedence:subject:mime-version:references:in-reply-to :message-id:date:to:from:delivered-to; bh=vX6Spzzu2vGXLWWZfD8aH92ZpFAo4JqG6tYKTGa40oo=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=Ozc5r3WkPZEQvdUezuu5NkxwFsGGJB9ktuUjUwoOl7pbLgTmYKppm1xnLN0XCstk2r lZnweVR81rwU+OeJwU/r2k5ZpcxCyd40dtPJG1fC+KtizRk1UD4AWCyYfCcg0DACDOUI bPZbjUo9rNqKN1nAzPSdiAFsmHczZJhUUGUTE5f4kSF0NolayqDJDBJTLZJHgPu9KRtl Dk6E8HoGf7LlfflziWq/hI6ZezvBRj58bpIlcVt6AA/B8MzHjDYCInfXsIj7WzysWC26 wyANftdOOUvO7q5Fe/3pEVYKUm0Q5YxVOkGCAt4vq8hQeVbbsNsVKZmiCX5DiwI5hbnh HhcQ==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id x11-20020a170906710b00b00a4455153b56si412729ejj.458.2024.02.29.08.24.46; Thu, 29 Feb 2024 08:24:47 -0800 (PST) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 9658868D1AD; Thu, 29 Feb 2024 18:24:35 +0200 (EET) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from alt2.a-painless.mh.aa.net.uk (alt2.a-painless.mh.aa.net.uk [81.187.30.51]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 1280668D162 for ; Thu, 29 Feb 2024 18:24:29 +0200 (EET) Received: from c.e.9.3.3.0.b.1.e.3.4.b.6.2.c.9.0.5.8.0.9.1.8.0.0.b.8.0.1.0.0.2.ip6.arpa ([2001:8b0:819:850:9c26:b43e:1b03:39ec] helo=andrews-2024-laptop.lan) by painless-a.thn.aa.net.uk with esmtp (Exim 4.96) (envelope-from ) id 1rfjCu-00DkRE-1f; Thu, 29 Feb 2024 16:24:28 +0000 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Thu, 29 Feb 2024 16:23:06 +0000 Message-ID: <20240229162424.850294-2-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240229162424.850294-1-ffmpeg-devel@pileofstuff.org> References: <20240229162424.850294-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 1/2] avformat: harmonise "- {decoding, encoding, demuxing, muxing}: " comments 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 Cc: Andrew Sayers Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: QvJNARnRwBCy There seems to be a convention for documenting ownership: /** * - encoding: (who sets this in encoding context) * - decoding: (who sets this in decoding context) */ int foo; Ensure all such comments start with a "-" and use lower case, so doxygen formats them as a bulleted lists instead of one long paragraph. Signed-off-by: Andrew Sayers --- libavformat/avformat.h | 67 +++++++++++++++++++++--------------------- 1 file changed, 34 insertions(+), 33 deletions(-) diff --git a/libavformat/avformat.h b/libavformat/avformat.h index f4506f4cf1..35b7f78ec7 100644 --- a/libavformat/avformat.h +++ b/libavformat/avformat.h @@ -849,8 +849,8 @@ typedef struct AVStream { int index; /**< stream index in AVFormatContext */ /** * Format-specific stream ID. - * decoding: set by libavformat - * encoding: set by the user, replaced by libavformat if left unset + * - decoding: set by libavformat + * - encoding: set by the user, replaced by libavformat if left unset */ int id; @@ -871,13 +871,13 @@ typedef struct AVStream { * This is the fundamental unit of time (in seconds) in terms * of which frame timestamps are represented. * - * decoding: set by libavformat - * encoding: May be set by the caller before avformat_write_header() to - * provide a hint to the muxer about the desired timebase. In - * avformat_write_header(), the muxer will overwrite this field - * with the timebase that will actually be used for the timestamps - * written into the file (which may or may not be related to the - * user-provided one, depending on the format). + * - decoding: set by libavformat + * - encoding: May be set by the caller before avformat_write_header() to + * provide a hint to the muxer about the desired timebase. In + * avformat_write_header(), the muxer will overwrite this field + * with the timebase that will actually be used for the timestamps + * written into the file (which may or may not be related to the + * user-provided one, depending on the format). */ AVRational time_base; @@ -896,8 +896,9 @@ typedef struct AVStream { * If a source file does not specify a duration, but does specify * a bitrate, this value will be estimated from bitrate and file size. * - * Encoding: May be set by the caller before avformat_write_header() to - * provide a hint to the muxer about the estimated duration. + * - decoding: set by libavformat + * - encoding: may be set by the caller before avformat_write_header() to + * provide a hint to the muxer about the estimated duration. */ int64_t duration; @@ -935,8 +936,8 @@ typedef struct AVStream { * For streams with AV_DISPOSITION_ATTACHED_PIC disposition, this packet * will contain the attached picture. * - * decoding: set by libavformat, must not be modified by the caller. - * encoding: unused + * - decoding: set by libavformat, must not be modified by the caller. + * - encoding: unused */ AVPacket attached_pic; @@ -1203,16 +1204,16 @@ typedef struct AVStreamGroup { /** * Group type-specific group ID. * - * decoding: set by libavformat - * encoding: may set by the user + * - decoding: set by libavformat + * - encoding: may set by the user */ int64_t id; /** * Group type * - * decoding: set by libavformat on group creation - * encoding: set by avformat_stream_group_create() + * - decoding: set by libavformat on group creation + * - encoding: set by avformat_stream_group_create() */ enum AVStreamGroupParamsType type; @@ -1534,19 +1535,19 @@ typedef struct AVFormatContext { /** * Forced video codec_id. - * Demuxing: Set by user. + * - demuxing: Set by user. */ enum AVCodecID video_codec_id; /** * Forced audio codec_id. - * Demuxing: Set by user. + * - demuxing: Set by user. */ enum AVCodecID audio_codec_id; /** * Forced subtitle codec_id. - * Demuxing: Set by user. + * - demuxing: Set by user. */ enum AVCodecID subtitle_codec_id; @@ -1622,11 +1623,11 @@ typedef struct AVFormatContext { /** * Custom interrupt callbacks for the I/O layer. * - * demuxing: set by the user before avformat_open_input(). - * muxing: set by the user before avformat_write_header() - * (mainly useful for AVFMT_NOFILE formats). The callback - * should also be passed to avio_open2() if it's used to - * open the file. + * - demuxing: set by the user before avformat_open_input(). + * - muxing: set by the user before avformat_write_header() + * (mainly useful for AVFMT_NOFILE formats). The callback + * should also be passed to avio_open2() if it's used to + * open the file. */ AVIOInterruptCB interrupt_callback; @@ -1828,7 +1829,7 @@ typedef struct AVFormatContext { * Forced video codec. * This allows forcing a specific decoder, even when there are multiple with * the same codec_id. - * Demuxing: Set by user + * - demuxing: Set by user */ const struct AVCodec *video_codec; @@ -1836,7 +1837,7 @@ typedef struct AVFormatContext { * Forced audio codec. * This allows forcing a specific decoder, even when there are multiple with * the same codec_id. - * Demuxing: Set by user + * - demuxing: Set by user */ const struct AVCodec *audio_codec; @@ -1844,7 +1845,7 @@ typedef struct AVFormatContext { * Forced subtitle codec. * This allows forcing a specific decoder, even when there are multiple with * the same codec_id. - * Demuxing: Set by user + * - demuxing: Set by user */ const struct AVCodec *subtitle_codec; @@ -1852,14 +1853,14 @@ typedef struct AVFormatContext { * Forced data codec. * This allows forcing a specific decoder, even when there are multiple with * the same codec_id. - * Demuxing: Set by user + * - demuxing: Set by user */ const struct AVCodec *data_codec; /** * Number of bytes to be written as padding in a metadata header. - * Demuxing: Unused. - * Muxing: Set by user. + * - demuxing: Unused. + * - muxing: Set by user. */ int metadata_header_padding; @@ -1876,7 +1877,7 @@ typedef struct AVFormatContext { /** * Output timestamp offset, in microseconds. - * Muxing: set by user + * - muxing: set by user */ int64_t output_ts_offset; @@ -1890,7 +1891,7 @@ typedef struct AVFormatContext { /** * Forced Data codec_id. - * Demuxing: Set by user. + * - demuxing: Set by user. */ enum AVCodecID data_codec_id; From patchwork Thu Feb 29 16:23:07 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Sayers X-Patchwork-Id: 46656 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:a919:b0:19e:cdac:8cce with SMTP id cd25csp707736pzb; Thu, 29 Feb 2024 08:24:56 -0800 (PST) X-Forwarded-Encrypted: i=2; AJvYcCXZHWhUEMgf35RUIZpjavyoOAKNZfqREKR+bhuHmTWaBA3RLly6H0okUBOK+JVbKSzhZI/SvKl5YMRSIRcrjbRY8I7wuIVdURNQ2A== X-Google-Smtp-Source: AGHT+IH91RJwgRQFcZhb4M6zuDNJASQQpI2f6QoNhkT0Bos2ro2LF8jeNp5QupK6CZ0YpDLlq0si X-Received: by 2002:a17:906:4152:b0:a3f:2259:da62 with SMTP id l18-20020a170906415200b00a3f2259da62mr1829913ejk.52.1709223896283; Thu, 29 Feb 2024 08:24:56 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1709223896; cv=none; d=google.com; s=arc-20160816; b=egc1tb+a5MKXVLbh5AQWQCWdcM8yehdAaMVckT8PhE3vHIUHXHfcTEvvmJBTc2ErBY ndkRPPoLNFDx8KgE5oLnT7QkowGiMAioufKa3m3JdH3l+SK5TGKQiqpo0mhiMUgXMOVc Ic0QRzljQgg3rn7A+ZJAtbpwMe31pxNTe5DJa0iO0GLV87l/Z56AED9a5TPgnSPebETi 1owUcPDK1ZbNx3Tg+Q9VQEKj7UkWnbO9ZQYujgdop85DzOALHxt/Ufkm9PyaP6V4xkz8 NyIF2wP7snV3uQX6qPVQSPjlo16/Fb/4uo7QjPQeEAaY+CwmdWhNQhZ+BlZMP1u/t3eT a1Gw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:cc:reply-to :list-subscribe:list-help:list-post:list-archive:list-unsubscribe :list-id:precedence:subject:mime-version:references:in-reply-to :message-id:date:to:from:delivered-to; bh=5uWjWcLAML6FkkmCJbyjunvGy7dcVk7gNvmp1mL26MU=; fh=73ExZnkQ8FYbu/qeQNmI0dtHCfShNh8/NmZJs1umltM=; b=R9jUDBG3sknZ9sXDoS7NspIIRFw0RX7RlfVI8Cq2oBWViBoBk3hi4ysq47x3FzBBAJ yifIcApMhHLkPtHv1BYNph1SsHAD3lOW1OHgOjQe89QNHc9MsmvIWy7eyw8opoOKERRg ZX0uOsvkfKygC2DBhGRpKhlm1s8zHHZyDVvi5kYoRvbUrX8TMW/uTPvGlws0gK4kVyYs ddFwBwc/AxzMLpj1JzsrPCF+swZq19RZ+feA1BEp+EWMi4lu2jeZOzPUS9QniKEW3Obi e1W/Mek3wMJYABZWmlzSC7TcvluqEc6W3KR2Xy9Wk9AE4w2moxLPX6R1osqvRIds7cY7 Nkrg==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id br17-20020a170906d15100b00a43f2be6a6esi700221ejb.592.2024.02.29.08.24.55; Thu, 29 Feb 2024 08:24:56 -0800 (PST) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 82F4F68D1B4; Thu, 29 Feb 2024 18:24:36 +0200 (EET) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from alt2.a-painless.mh.aa.net.uk (alt2.a-painless.mh.aa.net.uk [81.187.30.51]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 551E268D125 for ; Thu, 29 Feb 2024 18:24:29 +0200 (EET) Received: from c.e.9.3.3.0.b.1.e.3.4.b.6.2.c.9.0.5.8.0.9.1.8.0.0.b.8.0.1.0.0.2.ip6.arpa ([2001:8b0:819:850:9c26:b43e:1b03:39ec] helo=andrews-2024-laptop.lan) by painless-a.thn.aa.net.uk with esmtp (Exim 4.96) (envelope-from ) id 1rfjCu-00DkRE-2Z; Thu, 29 Feb 2024 16:24:28 +0000 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Thu, 29 Feb 2024 16:23:07 +0000 Message-ID: <20240229162424.850294-3-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240229162424.850294-1-ffmpeg-devel@pileofstuff.org> References: <20240229162424.850294-1-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 2/2] all: harmonise "{Decoding, Encoding, Audio, Video}:" comments 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 Cc: Andrew Sayers Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: reb/M/9Q4y+y 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. 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). + * * @note The ASF header does NOT contain a correct start_time the ASF * demuxer must NOT set this. */ int64_t start_time; /** - * Decoding: duration of the stream, in stream time base. - * If a source file does not specify a duration, but does specify - * a bitrate, this value will be estimated from bitrate and file size. + * *Decoding:* + * + * Duration of the stream, in stream time base. + * + * If a source file does not specify a duration, but does specify + * a bitrate, this value will be estimated from bitrate and file size. * * - decoding: set by libavformat * - encoding: may be set by the caller before avformat_write_header() to