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 56AF04B97D for ; Tue, 2 Jul 2024 10:49:10 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id E257068D37F; Tue, 2 Jul 2024 13:49:07 +0300 (EEST) 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 6276968C736 for ; Tue, 2 Jul 2024 13:49:02 +0300 (EEST) Received: from a.0.4.0.3.4.0.7.b.f.1.8.d.d.c.c.0.5.8.0.9.1.8.0.0.b.8.0.1.0.0.2.ip6.arpa ([2001:8b0:819:850:ccdd:81fb:7043:40a] helo=andrews-2024-laptop.sayers) by painless-a.thn.aa.net.uk with smtp (Exim 4.96) (envelope-from ) id 1sOb4H-004Pxk-0Y for ffmpeg-devel@ffmpeg.org; Tue, 02 Jul 2024 11:49:01 +0100 Date: Tue, 2 Jul 2024 11:49:00 +0100 From: Andrew Sayers To: FFmpeg development discussions and patches Message-ID: References: <20240702090917.319956-1-ffmpeg-devel@pileofstuff.org> <20240702090917.319956-3-ffmpeg-devel@pileofstuff.org> <171991394975.21847.16790103422177595236@lain.khirnov.net> <171991538463.21847.8552188356995036725@lain.khirnov.net> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <171991538463.21847.8552188356995036725@lain.khirnov.net> Subject: Re: [FFmpeg-devel] [PATCH v4 2/3] lavu/opt: Mention AV_OPT_FLAG_POST_INIT_SETTABLE_PARAM in more places 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 Tue, Jul 02, 2024 at 12:16:24PM +0200, Anton Khirnov wrote: > Quoting Andrew Sayers (2024-07-02 12:13:16) > > On Tue, Jul 02, 2024 at 11:52:29AM +0200, Anton Khirnov wrote: > > > Quoting Andrew Sayers (2024-07-02 11:08:39) > > > > An inattentive user might not see the explanation at the top of this file. > > > > Paste the explanation to all the places they might see it. > > > > > > Duplication is bad, and the premise doesn't work anyway. Inattentive > > > users will happily ignore arbitrary amounts of text. In fact the more > > > text there is, the more of it they will ignore. > > > Meanwhile you make actual information harder to find for people who > > > actually bother to read. > > > > That's a reasonable argument, but incompatible with your other one[1]. > > If users are inattentive and will ignore arbitrary amounts of text, > > the explanation needs to go in the one place they have to look (the > > macro name). > > I don't understand your point. In my other email I'm objecting to > breaking API for flimsy reasons, how is that related to documentation? I could be wrong, but I think this points to a fundamental issue... We normally talk about ABI (binary interface) and API (programming interface), then say "documentation" as if that's some separate thing. It would have been better if programmers had used a term like "ADI" (developer interface) instead, but the world didn't go that way. API is as intermingled with documentation as it is with ABI, and drawing a bright line between the two just causes problems. In this case, spelling it "AV_OPT_FLAG_RUNTIME_PARAM" isn't API, it's documentation. The compiler would work just the same if it had been called e.g. "AV_OPT_FLAG_15", the name is just there for us humans. This patch is about fixing the documentation, so the primary justification is that the old spelling mislead humans. Breaking the API is a side-effect, and I'd argue it's a net benefit, because it nudges external devs to fix their code. You can make the opposite argument, but either way it's incidental to the main goal of picking a spelling that unambiguously documents what the macro does. _______________________________________________ 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".