[FFmpeg-devel] [PATCH v4 3/4] all: Link to "context" from all contexts with documentation

[Andrew Sayers]

On Wed, May 15, 2024 at 06:46:19PM +0200, Lynne via ffmpeg-devel wrote:
> On 15/05/2024 17:54, Andrew Sayers wrote:
> > Some headings needed to be rewritten to accomodate the text,
> > (hopefully) without changing the meaning.
> > ---
> >   libavcodec/aac/aacdec.h            |  2 +-
> >   libavcodec/aacenc.h                |  2 +-
> >   libavcodec/ac3enc.h                |  2 +-
> >   libavcodec/amfenc.h                |  2 +-
> >   libavcodec/atrac.h                 |  2 +-
> >   libavcodec/avcodec.h               |  3 ++-
> >   libavcodec/bsf.h                   |  2 +-
> >   libavcodec/cbs.h                   |  2 +-
> >   libavcodec/d3d11va.h               |  3 +--
> >   libavcodec/h264dsp.h               |  2 +-
> >   libavcodec/h264pred.h              |  2 +-
> >   libavcodec/mediacodec.h            |  2 +-
> >   libavcodec/mpegaudiodec_template.c |  2 +-
> >   libavcodec/pthread_frame.c         |  4 ++--
> >   libavcodec/qsv.h                   |  6 ++++--
> >   libavcodec/sbr.h                   |  2 +-
> >   libavcodec/smacker.c               |  2 +-
> >   libavcodec/vdpau.h                 |  3 ++-
> >   libavcodec/videotoolbox.h          |  5 +++--
> >   libavfilter/avfilter.h             |  2 +-
> >   libavformat/avformat.h             |  3 ++-
> >   libavformat/avio.h                 |  3 ++-
> >   libavutil/audio_fifo.h             |  2 +-
> >   libavutil/hwcontext.h              | 21 ++++++++++++---------
> >   libavutil/hwcontext_cuda.h         |  2 +-
> >   libavutil/hwcontext_d3d11va.h      |  4 ++--
> >   libavutil/hwcontext_d3d12va.h      |  6 +++---
> >   libavutil/hwcontext_drm.h          |  2 +-
> >   libavutil/hwcontext_dxva2.h        |  4 ++--
> >   libavutil/hwcontext_mediacodec.h   |  2 +-
> >   libavutil/hwcontext_opencl.h       |  4 ++--
> >   libavutil/hwcontext_qsv.h          |  4 ++--
> >   libavutil/hwcontext_vaapi.h        |  6 +++---
> >   libavutil/hwcontext_vdpau.h        |  2 +-
> >   libavutil/hwcontext_vulkan.h       |  4 ++--
> >   libavutil/lfg.h                    |  2 +-
> >   36 files changed, 66 insertions(+), 57 deletions(-)
> 
> I still don't like this part. There's no reason to link this everywhere when
> no one will be bothered to. The document alone is enough IMO.

Readers who don't already know the word "context" need a sign that it's a word
they need to pay attention to.  For example, I come from an OOP background
where the word "object" is used so widely, it simply never comes up.

In fact, I'm probably not the only person who followed the link to AVClass
instead, which just makes FFmpeg look like a failed attempt at OOP if you don't
know about contexts.

Linking widely lets an attentive reader see this *before* they get the wrong
end of the stick, and gives an overwhelmed newbie enough hints that this is a
word they need to pay attention to.

To underline the previous point - an attentive reader could probably make do
with e.g. just links from AVClass and a handful of the most popular contexts.
But newbies are often inefficient learners who need many reminders before
they stop paying attention to random things.  So linking as widely as possible
makes the project more accessible to people with less experience.