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 D4526474E4 for ; Sat, 9 Mar 2024 16:14:36 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 9697868CC91; Sat, 9 Mar 2024 18:14:33 +0200 (EET) Received: from mail-wr1-f52.google.com (mail-wr1-f52.google.com [209.85.221.52]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 109C968C455 for ; Sat, 9 Mar 2024 18:14:27 +0200 (EET) Received: by mail-wr1-f52.google.com with SMTP id ffacd0b85a97d-33e4f15710aso960233f8f.2 for ; Sat, 09 Mar 2024 08:14:27 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1710000865; x=1710605665; darn=ffmpeg.org; h=user-agent:in-reply-to:content-disposition:mime-version:references :mail-followup-to:message-id:subject:cc:to:from:date:from:to:cc :subject:date:message-id:reply-to; bh=j5k/chBhCs8cDgb+SBf6q4nrq4I6SgldfPL73v4gMVE=; b=EhPjk7bmenoNXfjVsfzsc3260ZShHsW6BDvyNalduq6r6kMFzDT80dbie6ElE2+G64 P+0etQZWqy4z5Y51vni10Igg3f/TmzGLjbhUsONdAiMLqdMuvIuosXB7feDgcZ42Uiky kf4Ac+fy8MJfNpkMIXg1GQcWTqmphgJdnEv1J5K2zq7WdCpD87xkvkN9nYK0sMCTeD6z umFMeNVUlObA995FLMRyk4sPyJF7fH1hFHFf41UasPje9B6l1IB9mBNWKLxQVQ/VxkuL zS77pBe4HUwFocE4LUTH+dimXkpX43J8vpkaSWTrglvFnUQowaKgkoJ+HP7yURJNSfPX vBiw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1710000865; x=1710605665; h=user-agent:in-reply-to:content-disposition:mime-version:references :mail-followup-to:message-id:subject:cc:to:from:date :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=j5k/chBhCs8cDgb+SBf6q4nrq4I6SgldfPL73v4gMVE=; b=tFrvdn/aTKBlvmgtouxj29pQLVbZnrPp8dBj6BjpET/NNT3r4i+jB/g1EjgC5+vOA/ qP5p9Nw9pzxuw4cbpH5ICVmXgLdGtVO56+VwiMeFlRjukPSmrlU6PGvGOgXWWP7NFn0+ URAPSifXuZZLGibJcyhvqZE34L6iYChVsI9hxUGySP2lxiOPlmSO9cX+kNNb9OAcWJ43 hiyugcMQhaLeZKshTIKv9QbcBYnlGfBpR+OXmKatSSEdWCJX01Yvp0mxiuuPBpElTQT0 wexCfLySuEp3/Zv+dyWX9aXhDERDGdWyOzrtTKivt+Bl0VTmhTRyMQUMc0YBeik6tZq/ 4igQ== X-Gm-Message-State: AOJu0YxifyVtDTM/1TSKOo+Kq46bFptCHweB/2+TSU4DtxfFP8w26ZCV y/HDWAxvcFnKJAMXZOPYdwxOlUXtXp6eycROmUJ01EXGGM3JNEAjFxguESlr X-Google-Smtp-Source: AGHT+IEp+KzPAG/tDqjVGUiioI3oKbNr91cSoIyb03UW3zp4MlqJoethh9acXEXM/kgBU37/ZyHbcQ== X-Received: by 2002:adf:ff90:0:b0:33d:3098:3ccf with SMTP id j16-20020adfff90000000b0033d30983ccfmr1577621wrr.33.1710000865207; Sat, 09 Mar 2024 08:14:25 -0800 (PST) Received: from mariano ([188.210.239.79]) by smtp.gmail.com with ESMTPSA id r11-20020a05600c35cb00b004127057d6b9sm9539774wmq.35.2024.03.09.08.14.24 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 09 Mar 2024 08:14:24 -0800 (PST) Received: by mariano (Postfix, from userid 1000) id 69258BFCDC; Sat, 9 Mar 2024 17:14:22 +0100 (CET) Date: Sat, 9 Mar 2024 17:14:22 +0100 From: Stefano Sabatini To: FFmpeg development discussions and patches Message-ID: Mail-Followup-To: FFmpeg development discussions and patches , Andrew Sayers References: <20240229162424.850294-1-ffmpeg-devel@pileofstuff.org> <20240229162424.850294-3-ffmpeg-devel@pileofstuff.org> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <20240229162424.850294-3-ffmpeg-devel@pileofstuff.org> User-Agent: Mutt/2.1.4 (2021-12-11) Subject: Re: [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 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 date Thursday 2024-02-29 16:23:07 +0000, Andrew Sayers wrote: > 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. I still don't understand what you mean by "ownership" and "meaning" and their difference. To me they look like the same thing, i.e. they define the semantics depending on the operation context (encoding/decoding). In addition to this, there might be a difference releated to the media content. To distinguish the two, I'd say "operational" and "media" context. > 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). > + * This conventions seems at odd with the prevoius patch, where you was preferring the - decoding/- encoding style. [...] _______________________________________________ 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".