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

2024-05-16 Thread 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.
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".

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

2024-05-15 Thread Lynne via ffmpeg-devel 

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.


OpenPGP_0xA2FEA5F03F034464.asc
Description: OpenPGP public key


OpenPGP_signature.asc
Description: OpenPGP digital signature
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".

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

2024-05-15 Thread Andrew Sayers 
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(-)

diff --git a/libavcodec/aac/aacdec.h b/libavcodec/aac/aacdec.h
index eed53c6c96..1d991a3c63 100644
--- a/libavcodec/aac/aacdec.h
+++ b/libavcodec/aac/aacdec.h
@@ -253,7 +253,7 @@ typedef struct AACDecDSP {
 } AACDecDSP;
 
 /**
- * main AAC decoding context
+ * main AAC decoding @ref md_doc_2context "context"
  */
 struct AACDecContext {
 const struct AVClass  *class;
diff --git a/libavcodec/aacenc.h b/libavcodec/aacenc.h
index d07960620e..1a645f4719 100644
--- a/libavcodec/aacenc.h
+++ b/libavcodec/aacenc.h
@@ -207,7 +207,7 @@ typedef struct AACPCEInfo {
 } AACPCEInfo;
 
 /**
- * AAC encoder context
+ * AAC encoder @ref md_doc_2context "context"
  */
 typedef struct AACEncContext {
 AVClass *av_class;
diff --git a/libavcodec/ac3enc.h b/libavcodec/ac3enc.h
index 30812617cc..c725007077 100644
--- a/libavcodec/ac3enc.h
+++ b/libavcodec/ac3enc.h
@@ -152,7 +152,7 @@ typedef struct AC3Block {
 } AC3Block;
 
 /**
- * AC-3 encoder private context.
+ * AC-3 encoder private @ref md_doc_2context "context"
  */
 typedef struct AC3EncodeContext {
 AVClass *av_class;  ///< AVClass used for AVOption
diff --git a/libavcodec/amfenc.h b/libavcodec/amfenc.h
index 2dbd378ef8..f142ede63a 100644
--- a/libavcodec/amfenc.h
+++ b/libavcodec/amfenc.h
@@ -43,7 +43,7 @@ typedef struct AmfTraceWriter {
 } AmfTraceWriter;
 
 /**
-* AMF encoder context
+* AMF encoder @ref md_doc_2context "context"
 */
 
 typedef struct AmfContext {
diff --git a/libavcodec/atrac.h b/libavcodec/atrac.h
index 05208bbee6..1527e376a9 100644
--- a/libavcodec/atrac.h
+++ b/libavcodec/atrac.h
@@ -39,7 +39,7 @@ typedef struct AtracGainInfo {
 } AtracGainInfo;
 
 /**
- *  Gain compensation context structure.
+ *  Gain compensation @ref md_doc_2context "context"
  */
 typedef struct AtracGCContext {
 float   gain_tab1[16];  ///< gain compensation level table
diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 2da63c87ea..4f7a5aa80d 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -430,7 +430,8 @@ typedef struct RcOverride{
 #define AV_GET_ENCODE_BUFFER_FLAG_REF (1 << 0)
 
 /**
- * main external API structure.
+ * @ref md_doc_2context "Context" for an encode or decode session
+ *
  * New fields can be added to the end with minor version bumps.
  * Removal, reordering and changes to existing fields require a major
  * version bump.
diff --git a/libavcodec/bsf.h b/libavcodec/bsf.h
index a09c69f242..bf79afa7cc 100644
--- a/libavcodec/bsf.h
+++ b/libavcodec/bsf.h
@@ -56,7 +56,7 @@
  */
 
 /**
- * The bitstream filter state.
+ * Bitstream filter @ref md_doc_2context "context"
  *
  * This struct must be allocated with av_bsf_alloc() and freed with
  * av_bsf_free().
diff --git a/libavcodec/cbs.h b/libavcodec/cbs.h
index d479b1ac2d..0ff64d2fef 100644
--- a/libavcodec/cbs.h
+++ b/libavcodec/cbs.h
@@ -214,7 +214,7 @@ typedef void (*CBSTraceWriteCallback)(void *trace_context,
   int64_t value);
 
 /**
- * Context structure for coded bitstream operations.
+ * @ref md_doc_2context "Context" structure for coded bitstream operations.
  */
 typedef struct CodedBitstreamContext {
 /**
diff --git a/libavcodec/d3d11va.h

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

2024-05-02 Thread Zhao Zhili 


> On May 2, 2024, at 21:27, Andrew Sayers  wrote:
> 
> On Thu, May 02, 2024 at 09:00:42PM +0800, Zhao Zhili wrote:
>> 
>> 
>>> On May 2, 2024, at 19:01, Lynne  wrote:
>>> 
>>> Apr 29, 2024, 11:24 by ffmpeg-de...@pileofstuff.org:
>>> 
 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(-)
 
 diff --git a/libavcodec/aac/aacdec.h b/libavcodec/aac/aacdec.h
 index 4cf764e2e9..71d61813f4 100644
 --- a/libavcodec/aac/aacdec.h
 +++ b/libavcodec/aac/aacdec.h
 @@ -248,7 +248,7 @@ typedef struct AACDecDSP {
 } AACDecDSP;
 
 /**
 - * main AAC decoding context
 + * main AAC decoding @ref md_doc_2context "context"
 */
 struct AACDecContext {
 const struct AVClass  *class;
 diff --git a/libavcodec/aacenc.h b/libavcodec/aacenc.h
 index d07960620e..1a645f4719 100644
 --- a/libavcodec/aacenc.h
 +++ b/libavcodec/aacenc.h
 @@ -207,7 +207,7 @@ typedef struct AACPCEInfo {
 } AACPCEInfo;
 
 /**
 - * AAC encoder context
 + * AAC encoder @ref md_doc_2context "context"
 */
 typedef struct AACEncContext {
 AVClass *av_class;
 diff --git a/libavcodec/ac3enc.h b/libavcodec/ac3enc.h
 index 30812617cc..c725007077 100644
 --- a/libavcodec/ac3enc.h
 +++ b/libavcodec/ac3enc.h
 @@ -152,7 +152,7 @@ typedef struct AC3Block {
 } AC3Block;
 
 /**
 - * AC-3 encoder private context.
 + * AC-3 encoder private @ref md_doc_2context "context"
 */
 typedef struct AC3EncodeContext {
 AVClass *av_class;  ///< AVClass used for AVOption
 diff --git a/libavcodec/amfenc.h b/libavcodec/amfenc.h
 index 2dbd378ef8..f142ede63a 100644
 --- a/libavcodec/amfenc.h
 +++ b/libavcodec/amfenc.h
 @@ -43,7 +43,7 @@ typedef struct AmfTraceWriter {
 } AmfTraceWriter;
 
 /**
 -* AMF encoder context
 +* AMF encoder @ref md_doc_2context "context"
 */
 
 typedef struct AmfContext {
 diff --git a/libavcodec/atrac.h b/libavcodec/atrac.h
 index 05208bbee6..1527e376a9 100644
 --- a/libavcodec/atrac.h
 +++ b/libavcodec/atrac.h
 @@ -39,7 +39,7 @@ typedef struct AtracGainInfo {
 } AtracGainInfo;
 
 /**
 - *  Gain compensation context structure.
 + *  Gain compensation @ref md_doc_2context "context"
 */
 typedef struct AtracGCContext {
 float   gain_tab1[16];  ///< gain compensation level table
 diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
 index 968009a192..9180fedca7 100644
 --- a/libavcodec/avcodec.h
 +++ b/libavcodec/avcodec.h
 @@ -430,7 +430,8 @@ typedef struct RcOverride{
 #define AV_GET_ENCODE_BUFFER_FLAG_REF (1 << 0)
 
 /**
 - * main external API structure.
 + * @ref md_doc_2context "Context" for an encode or decode session
 + *
 * New fields can be added to the end with minor version bumps.
 * Removal, reordering and changes to existing fields require a major
 * version bump.
 diff --git a/libavcodec/bsf.h b/libavcodec/bsf.h
 index a09c69f242..bf79afa7cc

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

2024-05-02 Thread Andrew Sayers 
On Thu, May 02, 2024 at 09:00:42PM +0800, Zhao Zhili wrote:
> 
> 
> > On May 2, 2024, at 19:01, Lynne  wrote:
> > 
> > Apr 29, 2024, 11:24 by ffmpeg-de...@pileofstuff.org:
> > 
> >> 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(-)
> >> 
> >> diff --git a/libavcodec/aac/aacdec.h b/libavcodec/aac/aacdec.h
> >> index 4cf764e2e9..71d61813f4 100644
> >> --- a/libavcodec/aac/aacdec.h
> >> +++ b/libavcodec/aac/aacdec.h
> >> @@ -248,7 +248,7 @@ typedef struct AACDecDSP {
> >> } AACDecDSP;
> >> 
> >> /**
> >> - * main AAC decoding context
> >> + * main AAC decoding @ref md_doc_2context "context"
> >> */
> >> struct AACDecContext {
> >> const struct AVClass  *class;
> >> diff --git a/libavcodec/aacenc.h b/libavcodec/aacenc.h
> >> index d07960620e..1a645f4719 100644
> >> --- a/libavcodec/aacenc.h
> >> +++ b/libavcodec/aacenc.h
> >> @@ -207,7 +207,7 @@ typedef struct AACPCEInfo {
> >> } AACPCEInfo;
> >> 
> >> /**
> >> - * AAC encoder context
> >> + * AAC encoder @ref md_doc_2context "context"
> >> */
> >> typedef struct AACEncContext {
> >> AVClass *av_class;
> >> diff --git a/libavcodec/ac3enc.h b/libavcodec/ac3enc.h
> >> index 30812617cc..c725007077 100644
> >> --- a/libavcodec/ac3enc.h
> >> +++ b/libavcodec/ac3enc.h
> >> @@ -152,7 +152,7 @@ typedef struct AC3Block {
> >> } AC3Block;
> >> 
> >> /**
> >> - * AC-3 encoder private context.
> >> + * AC-3 encoder private @ref md_doc_2context "context"
> >> */
> >> typedef struct AC3EncodeContext {
> >> AVClass *av_class;  ///< AVClass used for AVOption
> >> diff --git a/libavcodec/amfenc.h b/libavcodec/amfenc.h
> >> index 2dbd378ef8..f142ede63a 100644
> >> --- a/libavcodec/amfenc.h
> >> +++ b/libavcodec/amfenc.h
> >> @@ -43,7 +43,7 @@ typedef struct AmfTraceWriter {
> >> } AmfTraceWriter;
> >> 
> >> /**
> >> -* AMF encoder context
> >> +* AMF encoder @ref md_doc_2context "context"
> >> */
> >> 
> >> typedef struct AmfContext {
> >> diff --git a/libavcodec/atrac.h b/libavcodec/atrac.h
> >> index 05208bbee6..1527e376a9 100644
> >> --- a/libavcodec/atrac.h
> >> +++ b/libavcodec/atrac.h
> >> @@ -39,7 +39,7 @@ typedef struct AtracGainInfo {
> >> } AtracGainInfo;
> >> 
> >> /**
> >> - *  Gain compensation context structure.
> >> + *  Gain compensation @ref md_doc_2context "context"
> >> */
> >> typedef struct AtracGCContext {
> >> float   gain_tab1[16];  ///< gain compensation level table
> >> diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
> >> index 968009a192..9180fedca7 100644
> >> --- a/libavcodec/avcodec.h
> >> +++ b/libavcodec/avcodec.h
> >> @@ -430,7 +430,8 @@ typedef struct RcOverride{
> >> #define AV_GET_ENCODE_BUFFER_FLAG_REF (1 << 0)
> >> 
> >> /**
> >> - * main external API structure.
> >> + * @ref md_doc_2context "Context" for an encode or decode session
> >> + *
> >> * New fields can be added to the end with minor version bumps.
> >> * Removal, reordering and changes to existing fields require a major
> >> * version bump.
> >> diff --git a/libavcodec/bsf.h b/libavcodec/bsf.h
> >> index a09c69f242..bf79afa7cc 100644
> >> --- a/libavcodec/bsf.h
> >> +++ b/libavcodec/bs

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

2024-05-02 Thread Zhao Zhili 


> On May 2, 2024, at 19:01, Lynne  wrote:
> 
> Apr 29, 2024, 11:24 by ffmpeg-de...@pileofstuff.org:
> 
>> 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(-)
>> 
>> diff --git a/libavcodec/aac/aacdec.h b/libavcodec/aac/aacdec.h
>> index 4cf764e2e9..71d61813f4 100644
>> --- a/libavcodec/aac/aacdec.h
>> +++ b/libavcodec/aac/aacdec.h
>> @@ -248,7 +248,7 @@ typedef struct AACDecDSP {
>> } AACDecDSP;
>> 
>> /**
>> - * main AAC decoding context
>> + * main AAC decoding @ref md_doc_2context "context"
>> */
>> struct AACDecContext {
>> const struct AVClass  *class;
>> diff --git a/libavcodec/aacenc.h b/libavcodec/aacenc.h
>> index d07960620e..1a645f4719 100644
>> --- a/libavcodec/aacenc.h
>> +++ b/libavcodec/aacenc.h
>> @@ -207,7 +207,7 @@ typedef struct AACPCEInfo {
>> } AACPCEInfo;
>> 
>> /**
>> - * AAC encoder context
>> + * AAC encoder @ref md_doc_2context "context"
>> */
>> typedef struct AACEncContext {
>> AVClass *av_class;
>> diff --git a/libavcodec/ac3enc.h b/libavcodec/ac3enc.h
>> index 30812617cc..c725007077 100644
>> --- a/libavcodec/ac3enc.h
>> +++ b/libavcodec/ac3enc.h
>> @@ -152,7 +152,7 @@ typedef struct AC3Block {
>> } AC3Block;
>> 
>> /**
>> - * AC-3 encoder private context.
>> + * AC-3 encoder private @ref md_doc_2context "context"
>> */
>> typedef struct AC3EncodeContext {
>> AVClass *av_class;  ///< AVClass used for AVOption
>> diff --git a/libavcodec/amfenc.h b/libavcodec/amfenc.h
>> index 2dbd378ef8..f142ede63a 100644
>> --- a/libavcodec/amfenc.h
>> +++ b/libavcodec/amfenc.h
>> @@ -43,7 +43,7 @@ typedef struct AmfTraceWriter {
>> } AmfTraceWriter;
>> 
>> /**
>> -* AMF encoder context
>> +* AMF encoder @ref md_doc_2context "context"
>> */
>> 
>> typedef struct AmfContext {
>> diff --git a/libavcodec/atrac.h b/libavcodec/atrac.h
>> index 05208bbee6..1527e376a9 100644
>> --- a/libavcodec/atrac.h
>> +++ b/libavcodec/atrac.h
>> @@ -39,7 +39,7 @@ typedef struct AtracGainInfo {
>> } AtracGainInfo;
>> 
>> /**
>> - *  Gain compensation context structure.
>> + *  Gain compensation @ref md_doc_2context "context"
>> */
>> typedef struct AtracGCContext {
>> float   gain_tab1[16];  ///< gain compensation level table
>> diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
>> index 968009a192..9180fedca7 100644
>> --- a/libavcodec/avcodec.h
>> +++ b/libavcodec/avcodec.h
>> @@ -430,7 +430,8 @@ typedef struct RcOverride{
>> #define AV_GET_ENCODE_BUFFER_FLAG_REF (1 << 0)
>> 
>> /**
>> - * main external API structure.
>> + * @ref md_doc_2context "Context" for an encode or decode session
>> + *
>> * New fields can be added to the end with minor version bumps.
>> * Removal, reordering and changes to existing fields require a major
>> * version bump.
>> diff --git a/libavcodec/bsf.h b/libavcodec/bsf.h
>> index a09c69f242..bf79afa7cc 100644
>> --- a/libavcodec/bsf.h
>> +++ b/libavcodec/bsf.h
>> @@ -56,7 +56,7 @@
>> */
>> 
>> /**
>> - * The bitstream filter state.
>> + * Bitstream filter @ref md_doc_2context "context"
>> *
>> * This struct must be allocated with av_bsf_alloc() and freed with
>> * av_bsf_free().
>> diff --git a/libavcodec/cbs.h b/libavcodec/cbs.h
>> index d479b1ac2d..0ff64d2fef 100644
>>

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

2024-05-02 Thread Andrew Sayers 
On Thu, May 02, 2024 at 01:01:43PM +0200, Lynne wrote:
> Apr 29, 2024, 11:24 by ffmpeg-de...@pileofstuff.org:
> 
> > 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(-)
> >
> > diff --git a/libavcodec/aac/aacdec.h b/libavcodec/aac/aacdec.h
> > index 4cf764e2e9..71d61813f4 100644
> > --- a/libavcodec/aac/aacdec.h
> > +++ b/libavcodec/aac/aacdec.h
> > @@ -248,7 +248,7 @@ typedef struct AACDecDSP {
> >  } AACDecDSP;
> >  
> >  /**
> > - * main AAC decoding context
> > + * main AAC decoding @ref md_doc_2context "context"
> >  */
> >  struct AACDecContext {
> >  const struct AVClass  *class;
> > diff --git a/libavcodec/aacenc.h b/libavcodec/aacenc.h
> > index d07960620e..1a645f4719 100644
> > --- a/libavcodec/aacenc.h
> > +++ b/libavcodec/aacenc.h
> > @@ -207,7 +207,7 @@ typedef struct AACPCEInfo {
> >  } AACPCEInfo;
> >  
> >  /**
> > - * AAC encoder context
> > + * AAC encoder @ref md_doc_2context "context"
> >  */
> >  typedef struct AACEncContext {
> >  AVClass *av_class;
> > diff --git a/libavcodec/ac3enc.h b/libavcodec/ac3enc.h
> > index 30812617cc..c725007077 100644
> > --- a/libavcodec/ac3enc.h
> > +++ b/libavcodec/ac3enc.h
> > @@ -152,7 +152,7 @@ typedef struct AC3Block {
> >  } AC3Block;
> >  
> >  /**
> > - * AC-3 encoder private context.
> > + * AC-3 encoder private @ref md_doc_2context "context"
> >  */
> >  typedef struct AC3EncodeContext {
> >  AVClass *av_class;  ///< AVClass used for AVOption
> > diff --git a/libavcodec/amfenc.h b/libavcodec/amfenc.h
> > index 2dbd378ef8..f142ede63a 100644
> > --- a/libavcodec/amfenc.h
> > +++ b/libavcodec/amfenc.h
> > @@ -43,7 +43,7 @@ typedef struct AmfTraceWriter {
> >  } AmfTraceWriter;
> >  
> >  /**
> > -* AMF encoder context
> > +* AMF encoder @ref md_doc_2context "context"
> >  */
> >  
> >  typedef struct AmfContext {
> > diff --git a/libavcodec/atrac.h b/libavcodec/atrac.h
> > index 05208bbee6..1527e376a9 100644
> > --- a/libavcodec/atrac.h
> > +++ b/libavcodec/atrac.h
> > @@ -39,7 +39,7 @@ typedef struct AtracGainInfo {
> >  } AtracGainInfo;
> >  
> >  /**
> > - *  Gain compensation context structure.
> > + *  Gain compensation @ref md_doc_2context "context"
> >  */
> >  typedef struct AtracGCContext {
> >  float   gain_tab1[16];  ///< gain compensation level table
> > diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
> > index 968009a192..9180fedca7 100644
> > --- a/libavcodec/avcodec.h
> > +++ b/libavcodec/avcodec.h
> > @@ -430,7 +430,8 @@ typedef struct RcOverride{
> >  #define AV_GET_ENCODE_BUFFER_FLAG_REF (1 << 0)
> >  
> >  /**
> > - * main external API structure.
> > + * @ref md_doc_2context "Context" for an encode or decode session
> > + *
> >  * New fields can be added to the end with minor version bumps.
> >  * Removal, reordering and changes to existing fields require a major
> >  * version bump.
> > diff --git a/libavcodec/bsf.h b/libavcodec/bsf.h
> > index a09c69f242..bf79afa7cc 100644
> > --- a/libavcodec/bsf.h
> > +++ b/libavcodec/bsf.h
> > @@ -56,7 +56,7 @@
> >  */
> >  
> >  /**
> > - * The bitstream filter state.
> > + * Bitstream filter @ref m

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

2024-05-02 Thread Lynne 
Apr 29, 2024, 11:24 by ffmpeg-de...@pileofstuff.org:

> 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(-)
>
> diff --git a/libavcodec/aac/aacdec.h b/libavcodec/aac/aacdec.h
> index 4cf764e2e9..71d61813f4 100644
> --- a/libavcodec/aac/aacdec.h
> +++ b/libavcodec/aac/aacdec.h
> @@ -248,7 +248,7 @@ typedef struct AACDecDSP {
>  } AACDecDSP;
>  
>  /**
> - * main AAC decoding context
> + * main AAC decoding @ref md_doc_2context "context"
>  */
>  struct AACDecContext {
>  const struct AVClass  *class;
> diff --git a/libavcodec/aacenc.h b/libavcodec/aacenc.h
> index d07960620e..1a645f4719 100644
> --- a/libavcodec/aacenc.h
> +++ b/libavcodec/aacenc.h
> @@ -207,7 +207,7 @@ typedef struct AACPCEInfo {
>  } AACPCEInfo;
>  
>  /**
> - * AAC encoder context
> + * AAC encoder @ref md_doc_2context "context"
>  */
>  typedef struct AACEncContext {
>  AVClass *av_class;
> diff --git a/libavcodec/ac3enc.h b/libavcodec/ac3enc.h
> index 30812617cc..c725007077 100644
> --- a/libavcodec/ac3enc.h
> +++ b/libavcodec/ac3enc.h
> @@ -152,7 +152,7 @@ typedef struct AC3Block {
>  } AC3Block;
>  
>  /**
> - * AC-3 encoder private context.
> + * AC-3 encoder private @ref md_doc_2context "context"
>  */
>  typedef struct AC3EncodeContext {
>  AVClass *av_class;  ///< AVClass used for AVOption
> diff --git a/libavcodec/amfenc.h b/libavcodec/amfenc.h
> index 2dbd378ef8..f142ede63a 100644
> --- a/libavcodec/amfenc.h
> +++ b/libavcodec/amfenc.h
> @@ -43,7 +43,7 @@ typedef struct AmfTraceWriter {
>  } AmfTraceWriter;
>  
>  /**
> -* AMF encoder context
> +* AMF encoder @ref md_doc_2context "context"
>  */
>  
>  typedef struct AmfContext {
> diff --git a/libavcodec/atrac.h b/libavcodec/atrac.h
> index 05208bbee6..1527e376a9 100644
> --- a/libavcodec/atrac.h
> +++ b/libavcodec/atrac.h
> @@ -39,7 +39,7 @@ typedef struct AtracGainInfo {
>  } AtracGainInfo;
>  
>  /**
> - *  Gain compensation context structure.
> + *  Gain compensation @ref md_doc_2context "context"
>  */
>  typedef struct AtracGCContext {
>  float   gain_tab1[16];  ///< gain compensation level table
> diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
> index 968009a192..9180fedca7 100644
> --- a/libavcodec/avcodec.h
> +++ b/libavcodec/avcodec.h
> @@ -430,7 +430,8 @@ typedef struct RcOverride{
>  #define AV_GET_ENCODE_BUFFER_FLAG_REF (1 << 0)
>  
>  /**
> - * main external API structure.
> + * @ref md_doc_2context "Context" for an encode or decode session
> + *
>  * New fields can be added to the end with minor version bumps.
>  * Removal, reordering and changes to existing fields require a major
>  * version bump.
> diff --git a/libavcodec/bsf.h b/libavcodec/bsf.h
> index a09c69f242..bf79afa7cc 100644
> --- a/libavcodec/bsf.h
> +++ b/libavcodec/bsf.h
> @@ -56,7 +56,7 @@
>  */
>  
>  /**
> - * The bitstream filter state.
> + * Bitstream filter @ref md_doc_2context "context"
>  *
>  * This struct must be allocated with av_bsf_alloc() and freed with
>  * av_bsf_free().
> diff --git a/libavcodec/cbs.h b/libavcodec/cbs.h
> index d479b1ac2d..0ff64d2fef 100644
> --- a/libavcodec/cbs.h
> +++ b/libavcodec/cbs.h
> @@ -214,7 +214,7 @@ typedef void (*CBSTraceWriteCallback)(

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

2024-04-29 Thread Andrew Sayers 
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(-)

diff --git a/libavcodec/aac/aacdec.h b/libavcodec/aac/aacdec.h
index 4cf764e2e9..71d61813f4 100644
--- a/libavcodec/aac/aacdec.h
+++ b/libavcodec/aac/aacdec.h
@@ -248,7 +248,7 @@ typedef struct AACDecDSP {
 } AACDecDSP;
 
 /**
- * main AAC decoding context
+ * main AAC decoding @ref md_doc_2context "context"
  */
 struct AACDecContext {
 const struct AVClass  *class;
diff --git a/libavcodec/aacenc.h b/libavcodec/aacenc.h
index d07960620e..1a645f4719 100644
--- a/libavcodec/aacenc.h
+++ b/libavcodec/aacenc.h
@@ -207,7 +207,7 @@ typedef struct AACPCEInfo {
 } AACPCEInfo;
 
 /**
- * AAC encoder context
+ * AAC encoder @ref md_doc_2context "context"
  */
 typedef struct AACEncContext {
 AVClass *av_class;
diff --git a/libavcodec/ac3enc.h b/libavcodec/ac3enc.h
index 30812617cc..c725007077 100644
--- a/libavcodec/ac3enc.h
+++ b/libavcodec/ac3enc.h
@@ -152,7 +152,7 @@ typedef struct AC3Block {
 } AC3Block;
 
 /**
- * AC-3 encoder private context.
+ * AC-3 encoder private @ref md_doc_2context "context"
  */
 typedef struct AC3EncodeContext {
 AVClass *av_class;  ///< AVClass used for AVOption
diff --git a/libavcodec/amfenc.h b/libavcodec/amfenc.h
index 2dbd378ef8..f142ede63a 100644
--- a/libavcodec/amfenc.h
+++ b/libavcodec/amfenc.h
@@ -43,7 +43,7 @@ typedef struct AmfTraceWriter {
 } AmfTraceWriter;
 
 /**
-* AMF encoder context
+* AMF encoder @ref md_doc_2context "context"
 */
 
 typedef struct AmfContext {
diff --git a/libavcodec/atrac.h b/libavcodec/atrac.h
index 05208bbee6..1527e376a9 100644
--- a/libavcodec/atrac.h
+++ b/libavcodec/atrac.h
@@ -39,7 +39,7 @@ typedef struct AtracGainInfo {
 } AtracGainInfo;
 
 /**
- *  Gain compensation context structure.
+ *  Gain compensation @ref md_doc_2context "context"
  */
 typedef struct AtracGCContext {
 float   gain_tab1[16];  ///< gain compensation level table
diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 968009a192..9180fedca7 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -430,7 +430,8 @@ typedef struct RcOverride{
 #define AV_GET_ENCODE_BUFFER_FLAG_REF (1 << 0)
 
 /**
- * main external API structure.
+ * @ref md_doc_2context "Context" for an encode or decode session
+ *
  * New fields can be added to the end with minor version bumps.
  * Removal, reordering and changes to existing fields require a major
  * version bump.
diff --git a/libavcodec/bsf.h b/libavcodec/bsf.h
index a09c69f242..bf79afa7cc 100644
--- a/libavcodec/bsf.h
+++ b/libavcodec/bsf.h
@@ -56,7 +56,7 @@
  */
 
 /**
- * The bitstream filter state.
+ * Bitstream filter @ref md_doc_2context "context"
  *
  * This struct must be allocated with av_bsf_alloc() and freed with
  * av_bsf_free().
diff --git a/libavcodec/cbs.h b/libavcodec/cbs.h
index d479b1ac2d..0ff64d2fef 100644
--- a/libavcodec/cbs.h
+++ b/libavcodec/cbs.h
@@ -214,7 +214,7 @@ typedef void (*CBSTraceWriteCallback)(void *trace_context,
   int64_t value);
 
 /**
- * Context structure for coded bitstream operations.
+ * @ref md_doc_2context "Context" structure for coded bitstream operations.
  */
 typedef struct CodedBitstreamContext {
 /**
diff --git a/libavcodec/d3d11va.h