[FFmpeg-devel] [PATCH v4 2/3] lavu/opt: Mention AV_OPT_FLAG_POST_INIT_SETTABLE_PARAM in more places

[Andrew Sayers]

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.