[FFmpeg-devel] Development process for explaining contexts (was Re: [PATCH v6 1/4] doc: Explain what "context" means)

[Stefano Sabatini]

On date Tuesday 2024-07-02 10:56:34 +0100, Andrew Sayers wrote:
> On Tue, Jul 02, 2024 at 12:16:21AM +0200, Stefano Sabatini wrote:
> > On date Sunday 2024-06-16 19:02:51 +0100, Andrew Sayers wrote:
> [...]
> > 
> > Andrew, sorry again for the slow reply. Thinking about the whole
> > discussion, I reckon I probably gave some bad advice, and I totally
> > understand how this is feeling dragging and burning out, and I'm sorry
> > for that.
> > 
> > I'm still on the idea of erring on the side of under-communicating for
> > the reference documentation (with the idea that too much information
> > is just too much, and would scare people away and make it harder to
> > maintain the documentation, as now you have to check in many places
> > when changing/updating it, resulting in contradicting content).
> > 
> > So at the moment I'd be willing to publish an abridged version of your
> > latest patch, with the suggested cuts - I can make the edit myself if
> > you prefer like that. This way we can get the non controversial parts
> > committed, and we can work on the other parts where there is no still
> > agreement.
> > 
> > Also, I'd like to hear opinions from other developers, although my
> > impression - from the scattered feedback I read - is that other
> > developers have the same feeling as me.
> > 
> > In general, having different channels for different targets would be
> > ideal, e.g. for articles and tutorials. For this it would be ideal to
> > have a blog entry for the project org, to simplify contributions from
> > contributors who don't want to setup a blog just for that and to
> > collect resources in a single place. In practice we lack this so this
> > is not an option at the moment (and the wiki is not the ideal place
> > too).
> 
> No problem about the delay, although my thinking has moved on a little
> (e.g. it turns out GIMP uses the word "context" in a completely different
> way than we do[1]).  But rather than argue over today's minutia, here's
> a big picture idea...
> 
> It sounds like your vision is for smaller, more disparate documentation;
> and you're willing to spend some time writing that up.  How would you feel
> about taking the AVClass/AVOptions bits from this document, and working them
> in to the existing AVClass/AVOptions documentation?  That would require a level
> of experience (and commit access) beyond what I can offer, after which we could
> come back here and uncontroversially trim that stuff out of this document.
> 

> For inspiration, here are some uninformed questions a newbie might ask:
> 

> * (reading AVClass) does the struct name mean I have to learn OOP before I can
>   use FFmpeg?

The answer is definitively no, the point of AVClass is keeping the
"core" functionality for a class of contexts.

> * (reading AVOptions) if the options API only works post-init for a subset of
>   options, should I just ignore this API and set the variables directly
>   whenever I like?

Nothing prevents directly accessing a struct, but then yuo will miss
the following benefits:
* ABI/API compatibility in case of field renames in the context struct
* validation
* higher level setting functionality (e.g. to set options from
  a dictionary or from a string encoding multiple options)

I'll try to write something (and probably we should have a dedicated
class.h header to decouple it from the logging functionality).