mbox series

[FFmpeg-devel,v6,0/4] doc: Explain what "context" means

Message ID 20240604144919.213799-1-ffmpeg-devel@pileofstuff.org
Headers show
Series doc: Explain what "context" means | expand

Message

Andrew Sayers June 4, 2024, 2:47 p.m. UTC 
I'm making a list of little documentation patches to submit as a set once this
patchset is done.  I've put Sw{r,s}Context on the list, and will think about
their relationship to other opaque AVOptions-enabled structs as part of that.
I don't see anything in that discussion that affects this patchset,
so let's park that discussion for now.

One thing we haven't talked about before, but is worth stating explicitly -
smart people tend to conflate "I can't think of anything complex about X"
with "there are no complex things about X", so this document needs to sell
people on the complexity of each problem before laying out the solution.
The AVOptions section is a particularly good example, tackling the implicit
question "can't you just use `getopt`?" first then moving on to describe how
it solves that problem.  Some parts of the document function as responses to 
questions an FFmpeg developer would never think to ask, because why would you 
even think to compare AVOptions with getopt?

This version emphasises how AVOptions should only be set during configuration.
It avoids the words "reflection" and "introspection" altogether, because IMHO
they imply an API that can be used in any stage of a struct's lifetime.

Aside: this is the latest in a series of issues where it initially seemed like
I was adding unnecessary terminology in places where it was confusing,
but turned out to be a symptom of a fundamental misunderstanding on my part.
If there's any such language remaining in this version, we should probably
look for those misunderstandings first and worry about language second.