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

[Andrew Sayers <ffmpeg-devel@pileofstuff.org>]

Some headings needed to be rewritten to accomodate the text,
(hopefully) without changing the meaning.
---
 libavcodec/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/d3d11va.h             |  3 +--
 libavcodec/mediacodec.h          |  2 +-
 libavcodec/qsv.h                 |  6 ++++--
 libavcodec/sbr.h                 |  2 +-
 libavcodec/vdpau.h               |  3 ++-
 libavcodec/videotoolbox.h        |  5 +++--
 libavfilter/avfilter.h           |  2 +-
 libavformat/avformat.h           |  3 ++-
 libavformat/avio.h               |  3 ++-
 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 ++--
 28 files changed, 57 insertions(+), 48 deletions(-)

diff --git a/libavcodec/aacdec.h b/libavcodec/aacdec.h
index 1b245f9258..3a5317cd54 100644
--- a/libavcodec/aacdec.h
+++ b/libavcodec/aacdec.h
@@ -181,7 +181,7 @@ typedef struct DynamicRangeControl {
 } DynamicRangeControl;
 
 /**
- * main AAC decoding context
+ * main AAC decoding @ref context "context"
  */
 typedef struct AACDecContext {
     const struct AVClass  *class;
diff --git a/libavcodec/aacenc.h b/libavcodec/aacenc.h
index 8899f90ac7..c91f99bc6c 100644
--- a/libavcodec/aacenc.h
+++ b/libavcodec/aacenc.h
@@ -193,7 +193,7 @@ typedef struct AACPCEInfo {
 } AACPCEInfo;
 
 /**
- * AAC encoder context
+ * AAC encoder @ref context "context"
  */
 typedef struct AACEncContext {
     AVClass *av_class;
diff --git a/libavcodec/ac3enc.h b/libavcodec/ac3enc.h
index 227744d27f..68d8736f7a 100644
--- a/libavcodec/ac3enc.h
+++ b/libavcodec/ac3enc.h
@@ -151,7 +151,7 @@ typedef struct AC3Block {
 } AC3Block;
 
 /**
- * AC-3 encoder private context.
+ * AC-3 encoder private @ref context "context"
  */
 typedef struct AC3EncodeContext {
     AVClass *av_class;                      ///< AVClass used for AVOption
diff --git a/libavcodec/amfenc.h b/libavcodec/amfenc.h
index 2dbd378ef8..71138e7f76 100644
--- a/libavcodec/amfenc.h
+++ b/libavcodec/amfenc.h
@@ -43,7 +43,7 @@ typedef struct AmfTraceWriter {
 } AmfTraceWriter;
 
 /**
-* AMF encoder context
+* AMF encoder @ref context "context"
 */
 
 typedef struct AmfContext {
diff --git a/libavcodec/atrac.h b/libavcodec/atrac.h
index 05208bbee6..acdd0a741a 100644
--- a/libavcodec/atrac.h
+++ b/libavcodec/atrac.h
@@ -39,7 +39,7 @@ typedef struct AtracGainInfo {
 } AtracGainInfo;
 
 /**
- *  Gain compensation context structure.
+ *  Gain compensation @ref context "context"
  */
 typedef struct AtracGCContext {
     float   gain_tab1[16];  ///< gain compensation level table
diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 968009a192..a1f1430dde 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 context "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..23c3cc87e4 100644
--- a/libavcodec/bsf.h
+++ b/libavcodec/bsf.h
@@ -56,7 +56,7 @@
  */
 
 /**
- * The bitstream filter state.
+ * Bitstream filter @ref context "context"
  *
  * This struct must be allocated with av_bsf_alloc() and freed with
  * av_bsf_free().
diff --git a/libavcodec/d3d11va.h b/libavcodec/d3d11va.h
index 27f40e5519..087c99f161 100644
--- a/libavcodec/d3d11va.h
+++ b/libavcodec/d3d11va.h
@@ -46,8 +46,7 @@
  */
 
 /**
- * This structure is used to provides the necessary configurations and data
- * to the Direct3D11 FFmpeg HWAccel implementation.
+ * @ref context "Context" for the Direct3D11 FFmpeg HWAccel implementation
  *
  * The application must make it available as AVCodecContext.hwaccel_context.
  *
diff --git a/libavcodec/mediacodec.h b/libavcodec/mediacodec.h
index 4e9b56a618..d983e7ff1a 100644
--- a/libavcodec/mediacodec.h
+++ b/libavcodec/mediacodec.h
@@ -26,7 +26,7 @@
 #include "libavcodec/avcodec.h"
 
 /**
- * This structure holds a reference to a android/view/Surface object that will
+ * @ref context "Context" for the android/view/Surface object that will
  * be used as output by the decoder.
  *
  */
diff --git a/libavcodec/qsv.h b/libavcodec/qsv.h
index c156b08d07..e75351ae27 100644
--- a/libavcodec/qsv.h
+++ b/libavcodec/qsv.h
@@ -26,8 +26,10 @@
 #include "libavutil/buffer.h"
 
 /**
- * This struct is used for communicating QSV parameters between libavcodec and
- * the caller. It is managed by the caller and must be assigned to
+ * @ref context "Context" for communicating QSV parameters between libavcodec
+ * and the caller.
+ *
+ * It is managed by the caller and must be assigned to
  * AVCodecContext.hwaccel_context.
  * - decoding: hwaccel_context must be set on return from the get_format()
  *             callback
diff --git a/libavcodec/sbr.h b/libavcodec/sbr.h
index fe3a39603a..65f7a6da8f 100644
--- a/libavcodec/sbr.h
+++ b/libavcodec/sbr.h
@@ -116,7 +116,7 @@ typedef struct SBRData {
 typedef struct SpectralBandReplication SpectralBandReplication;
 
 /**
- * aacsbr functions pointers
+ * aacsbr functions pointer @ref context "context"
  */
 typedef struct AACSBRContext {
     int (*sbr_lf_gen)(SpectralBandReplication *sbr,
diff --git a/libavcodec/vdpau.h b/libavcodec/vdpau.h
index 8021c25761..a9ff8b5f47 100644
--- a/libavcodec/vdpau.h
+++ b/libavcodec/vdpau.h
@@ -64,8 +64,9 @@ typedef int (*AVVDPAU_Render2)(struct AVCodecContext *, struct AVFrame *,
                                const VdpBitstreamBuffer *);
 
 /**
- * This structure is used to share data between the libavcodec library and
+ * @ref context "Context" to share data between the libavcodec library and
  * the client video application.
+ *
  * This structure will be allocated and stored in AVCodecContext.hwaccel_context
  * by av_vdpau_bind_context(). Members can be set by the user once
  * during initialization or through each AVCodecContext.get_buffer()
diff --git a/libavcodec/videotoolbox.h b/libavcodec/videotoolbox.h
index d68d76e400..ece008157c 100644
--- a/libavcodec/videotoolbox.h
+++ b/libavcodec/videotoolbox.h
@@ -49,8 +49,9 @@
 #include "libavutil/attributes.h"
 
 /**
- * This struct holds all the information that needs to be passed
- * between the caller and libavcodec for initializing Videotoolbox decoding.
+ * @ref context "Context" for information passed between the caller and libavcodec
+ * for initializing Videotoolbox decoding.
+ *
  * Its size is not a part of the public ABI, it must be allocated with
  * av_videotoolbox_alloc_context() and freed with av_free().
  */
diff --git a/libavfilter/avfilter.h b/libavfilter/avfilter.h
index a34e61f23c..41bdc30d89 100644
--- a/libavfilter/avfilter.h
+++ b/libavfilter/avfilter.h
@@ -403,7 +403,7 @@ unsigned avfilter_filter_pad_count(const AVFilter *filter, int is_output);
  */
 #define AVFILTER_THREAD_SLICE (1 << 0)
 
-/** An instance of a filter */
+/** @ref context "Context" for a filter */
 struct AVFilterContext {
     const AVClass *av_class;        ///< needed for av_log() and filters common options
 
diff --git a/libavformat/avformat.h b/libavformat/avformat.h
index 8afdcd9fd0..6bb08a0b0c 100644
--- a/libavformat/avformat.h
+++ b/libavformat/avformat.h
@@ -1241,7 +1241,8 @@ enum AVDurationEstimationMethod {
 };
 
 /**
- * Format I/O context.
+ * Format I/O @ref context "context"
+ *
  * 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/libavformat/avio.h b/libavformat/avio.h
index ebf611187d..e18d542377 100644
--- a/libavformat/avio.h
+++ b/libavformat/avio.h
@@ -146,7 +146,8 @@ enum AVIODataMarkerType {
 };
 
 /**
- * Bytestream IO Context.
+ * Bytestream I/O @ref context "context"
+ *
  * New public fields can be added with minor version bumps.
  * Removal, reordering and changes to existing public fields require
  * a major version bump.
diff --git a/libavutil/hwcontext.h b/libavutil/hwcontext.h
index bac30debae..f94f44906c 100644
--- a/libavutil/hwcontext.h
+++ b/libavutil/hwcontext.h
@@ -41,12 +41,13 @@ enum AVHWDeviceType {
 };
 
 /**
- * This struct aggregates all the (hardware/vendor-specific) "high-level" state,
- * i.e. state that is not tied to a concrete processing configuration.
- * E.g., in an API that supports hardware-accelerated encoding and decoding,
- * this struct will (if possible) wrap the state that is common to both encoding
- * and decoding and from which specific instances of encoders or decoders can be
- * derived.
+ * @ref context "Context" for (hardware/vendor-specific) "high-level" state.
+ *
+ * "High-level state" is anything that is not tied to a concrete processing
+ * configuration. E.g., in an API that supports hardware-accelerated encoding
+ * and decoding, this struct will (if possible) wrap the state that is common
+ * to both encoding and decoding and from which specific instances of encoders
+ * or decoders can be derived.
  *
  * This struct is reference-counted with the AVBuffer mechanism. The
  * av_hwdevice_ctx_alloc() constructor yields a reference, whose data field
@@ -103,9 +104,11 @@ typedef struct AVHWDeviceContext {
 } AVHWDeviceContext;
 
 /**
- * This struct describes a set or pool of "hardware" frames (i.e. those with
- * data not located in normal system memory). All the frames in the pool are
- * assumed to be allocated in the same way and interchangeable.
+ * @ref context "context" for a pool of "hardware" frames (those with
+ * data not located in normal system memory)
+ *
+ * All the frames in the pool are assumed to be allocated in the same way and
+ * interchangeable.
  *
  * This struct is reference-counted with the AVBuffer mechanism and tied to a
  * given AVHWDeviceContext instance. The av_hwframe_ctx_alloc() constructor
diff --git a/libavutil/hwcontext_cuda.h b/libavutil/hwcontext_cuda.h
index cbad434fea..befa978cf9 100644
--- a/libavutil/hwcontext_cuda.h
+++ b/libavutil/hwcontext_cuda.h
@@ -37,7 +37,7 @@
 typedef struct AVCUDADeviceContextInternal AVCUDADeviceContextInternal;
 
 /**
- * This struct is allocated as AVHWDeviceContext.hwctx
+ * This @ref context "context" is allocated as AVHWDeviceContext.hwctx
  */
 typedef struct AVCUDADeviceContext {
     CUcontext cuda_ctx;
diff --git a/libavutil/hwcontext_d3d11va.h b/libavutil/hwcontext_d3d11va.h
index 77d2d72f1b..eac7d6062a 100644
--- a/libavutil/hwcontext_d3d11va.h
+++ b/libavutil/hwcontext_d3d11va.h
@@ -40,7 +40,7 @@
 #include <stdint.h>
 
 /**
- * This struct is allocated as AVHWDeviceContext.hwctx
+ * This @ref context "context" is allocated as AVHWDeviceContext.hwctx
  */
 typedef struct AVD3D11VADeviceContext {
     /**
@@ -126,7 +126,7 @@ typedef struct AVD3D11FrameDescriptor {
 } AVD3D11FrameDescriptor;
 
 /**
- * This struct is allocated as AVHWFramesContext.hwctx
+ * This @ref context "context" is allocated as AVHWFramesContext.hwctx
  */
 typedef struct AVD3D11VAFramesContext {
     /**
diff --git a/libavutil/hwcontext_d3d12va.h b/libavutil/hwcontext_d3d12va.h
index ff06e6f2ef..d170f74b4d 100644
--- a/libavutil/hwcontext_d3d12va.h
+++ b/libavutil/hwcontext_d3d12va.h
@@ -37,7 +37,7 @@
 #include <d3d12video.h>
 
 /**
- * @brief This struct is allocated as AVHWDeviceContext.hwctx
+ * @brief This @ref context "context" is allocated as AVHWDeviceContext.hwctx
  *
  */
 typedef struct AVD3D12VADeviceContext {
@@ -78,7 +78,7 @@ typedef struct AVD3D12VADeviceContext {
 } AVD3D12VADeviceContext;
 
 /**
- * @brief This struct is used to sync d3d12 execution
+ * @brief This @ref context "context" is used to sync d3d12 execution
  *
  */
 typedef struct AVD3D12VASyncContext {
@@ -120,7 +120,7 @@ typedef struct AVD3D12VAFrame {
 } AVD3D12VAFrame;
 
 /**
- * @brief This struct is allocated as AVHWFramesContext.hwctx
+ * @brief This @ref context "context" is allocated as AVHWFramesContext.hwctx
  *
  */
 typedef struct AVD3D12VAFramesContext {
diff --git a/libavutil/hwcontext_drm.h b/libavutil/hwcontext_drm.h
index 42709f215e..b7b1bad171 100644
--- a/libavutil/hwcontext_drm.h
+++ b/libavutil/hwcontext_drm.h
@@ -152,7 +152,7 @@ typedef struct AVDRMFrameDescriptor {
 /**
  * DRM device.
  *
- * Allocated as AVHWDeviceContext.hwctx.
+ * This @ref context "context" is allocated as AVHWDeviceContext.hwctx.
  */
 typedef struct AVDRMDeviceContext {
     /**
diff --git a/libavutil/hwcontext_dxva2.h b/libavutil/hwcontext_dxva2.h
index e1b79bc0de..b77b7293ab 100644
--- a/libavutil/hwcontext_dxva2.h
+++ b/libavutil/hwcontext_dxva2.h
@@ -34,14 +34,14 @@
 #include <dxva2api.h>
 
 /**
- * This struct is allocated as AVHWDeviceContext.hwctx
+ * This @ref context "context" is allocated as AVHWDeviceContext.hwctx
  */
 typedef struct AVDXVA2DeviceContext {
     IDirect3DDeviceManager9 *devmgr;
 } AVDXVA2DeviceContext;
 
 /**
- * This struct is allocated as AVHWFramesContext.hwctx
+ * This @ref context "context" is allocated as AVHWFramesContext.hwctx
  */
 typedef struct AVDXVA2FramesContext {
     /**
diff --git a/libavutil/hwcontext_mediacodec.h b/libavutil/hwcontext_mediacodec.h
index fc0263cabc..39381b56c5 100644
--- a/libavutil/hwcontext_mediacodec.h
+++ b/libavutil/hwcontext_mediacodec.h
@@ -22,7 +22,7 @@
 /**
  * MediaCodec details.
  *
- * Allocated as AVHWDeviceContext.hwctx
+ * This @ref context "context" is allocated as AVHWDeviceContext.hwctx
  */
 typedef struct AVMediaCodecDeviceContext {
     /**
diff --git a/libavutil/hwcontext_opencl.h b/libavutil/hwcontext_opencl.h
index ef54486c95..fc5b1bb24f 100644
--- a/libavutil/hwcontext_opencl.h
+++ b/libavutil/hwcontext_opencl.h
@@ -58,7 +58,7 @@ typedef struct AVOpenCLFrameDescriptor {
 /**
  * OpenCL device details.
  *
- * Allocated as AVHWDeviceContext.hwctx
+ * This @ref context "context" is allocated as AVHWDeviceContext.hwctx
  */
 typedef struct AVOpenCLDeviceContext {
     /**
@@ -84,7 +84,7 @@ typedef struct AVOpenCLDeviceContext {
 /**
  * OpenCL-specific data associated with a frame pool.
  *
- * Allocated as AVHWFramesContext.hwctx.
+ * This @ref context "context" is allocated as AVHWFramesContext.hwctx.
  */
 typedef struct AVOpenCLFramesContext {
     /**
diff --git a/libavutil/hwcontext_qsv.h b/libavutil/hwcontext_qsv.h
index e2dba8ad83..c7cc88627b 100644
--- a/libavutil/hwcontext_qsv.h
+++ b/libavutil/hwcontext_qsv.h
@@ -30,7 +30,7 @@
  */
 
 /**
- * This struct is allocated as AVHWDeviceContext.hwctx
+ * This @ref context "context" is allocated as AVHWDeviceContext.hwctx
  */
 typedef struct AVQSVDeviceContext {
     mfxSession session;
@@ -48,7 +48,7 @@ typedef struct AVQSVDeviceContext {
 } AVQSVDeviceContext;
 
 /**
- * This struct is allocated as AVHWFramesContext.hwctx
+ * This @ref context "context" is allocated as AVHWFramesContext.hwctx
  */
 typedef struct AVQSVFramesContext {
     mfxFrameSurface1 *surfaces;
diff --git a/libavutil/hwcontext_vaapi.h b/libavutil/hwcontext_vaapi.h
index 0b2e071cb3..e1940a5fe0 100644
--- a/libavutil/hwcontext_vaapi.h
+++ b/libavutil/hwcontext_vaapi.h
@@ -63,7 +63,7 @@ enum {
 /**
  * VAAPI connection details.
  *
- * Allocated as AVHWDeviceContext.hwctx
+ * This @ref context "context" is allocated as AVHWDeviceContext.hwctx
  */
 typedef struct AVVAAPIDeviceContext {
     /**
@@ -83,7 +83,7 @@ typedef struct AVVAAPIDeviceContext {
 /**
  * VAAPI-specific data associated with a frame pool.
  *
- * Allocated as AVHWFramesContext.hwctx.
+ * This @ref context "context" is allocated as AVHWFramesContext.hwctx.
  */
 typedef struct AVVAAPIFramesContext {
     /**
@@ -105,7 +105,7 @@ typedef struct AVVAAPIFramesContext {
 /**
  * VAAPI hardware pipeline configuration details.
  *
- * Allocated with av_hwdevice_hwconfig_alloc().
+ * This struct is allocated with av_hwdevice_hwconfig_alloc().
  */
 typedef struct AVVAAPIHWConfig {
     /**
diff --git a/libavutil/hwcontext_vdpau.h b/libavutil/hwcontext_vdpau.h
index 1b7ea1e443..b26f7f171e 100644
--- a/libavutil/hwcontext_vdpau.h
+++ b/libavutil/hwcontext_vdpau.h
@@ -30,7 +30,7 @@
  */
 
 /**
- * This struct is allocated as AVHWDeviceContext.hwctx
+ * This @ref context "context" is allocated as AVHWDeviceContext.hwctx
  */
 typedef struct AVVDPAUDeviceContext {
     VdpDevice          device;
diff --git a/libavutil/hwcontext_vulkan.h b/libavutil/hwcontext_vulkan.h
index cbbd2390c1..d6897a96fa 100644
--- a/libavutil/hwcontext_vulkan.h
+++ b/libavutil/hwcontext_vulkan.h
@@ -39,7 +39,7 @@ typedef struct AVVkFrame AVVkFrame;
  */
 
 /**
- * Main Vulkan context, allocated as AVHWDeviceContext.hwctx.
+ * Main Vulkan @ref context "context", allocated as AVHWDeviceContext.hwctx.
  * All of these can be set before init to change what the context uses
  */
 typedef struct AVVulkanDeviceContext {
@@ -172,7 +172,7 @@ typedef enum AVVkFrameFlags {
 } AVVkFrameFlags;
 
 /**
- * Allocated as AVHWFramesContext.hwctx, used to set pool-specific options
+ * This @ref context "context" is allocated as AVHWFramesContext.hwctx, used to set pool-specific options
  */
 typedef struct AVVulkanFramesContext {
     /**
-- 
2.43.0

_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

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