[FFmpeg-devel] [PATCH 1/3] doc: Explain what "context" means

[Stefano Sabatini]

On date Saturday 2024-04-20 13:18:29 +0100, Andrew Sayers wrote:
> On 20/04/2024 08:25, Stefano Sabatini wrote:
> > On date Thursday 2024-04-18 16:06:12 +0100, Andrew Sayers wrote:
> > > Based largely on the explanation by Stefano Sabatini:
> > > https://ffmpeg.org/pipermail/ffmpeg-devel/2024-April/325854.html
> > > ---
> > >   doc/jargon.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++
> > >   1 file changed, 96 insertions(+)
> > >   create mode 100644 doc/jargon.md
> > > 
> > > diff --git a/doc/jargon.md b/doc/jargon.md
> > > new file mode 100644
> > > index 0000000000..3b78ffb61f
> > > --- /dev/null
> > > +++ b/doc/jargon.md
> > We currently have a single .md file in doc (for historical reason we
> > still stick to texinfo). Also how is this integrated into doxygen?
> 

> Doxygen automatically renders all /*.md and /doc/*.md files to pages at [1]
> which is the only place I'd know to look for this sort of thing. it seems
> like texinfo is more for man pages etc., which would be hard to link from
> doxygen?  By the way, a file called "jargon" seemed like a better idea than
> e.g. a "design_patterns" file or a section in AVClass.  I've rewritten the
> document completely based on your feedback - same markdown file for now,
> but happy to move/reformat.

If this is the case, probably we should move the files to a dedicated
directory (doxygen?) to avoid to mix too many things in the same
bundle (can be done as a separated patch though since we might think
about what we really want to include in the doxygen docs).

> The points below should be addressed by the new patch, so I'll let that
> speak for itself.  But there's a general issue that's worth mentioning...
> 

> Technically, it sounds like a more accurate description would be "Context
> is an FFmpeg convention that has become fairly rigorous over the years".
> But IMHO readers would uncharitably read that as "Context is some weird
> FFmpeg thing they're stuck with because they picked a pre-OOP language".
> Arguing "Context is a design pattern that groups objects by lifespan"
> emphasises the lessons a newbie can take from FFmpeg and use elsewhere,
> so they get more value from the time they spent reading the document.
> I've tried to write the document to start with the more useful argument,
> then gradually ease in to the more accurate one.

But, I don't think this is really something very rigourous, because it
is used in different "contexts" with sligthly different features
(e.g. you can have a structure named "context" but without an AVClass
or options).

And it's not really about lifespan, and not really specific for
FFmpeg, in C programming this is used to provide a "context" for
several "methods" operating on a given struct - so basically a light
implementation of an object-oriented-based API.

[...]