[FFmpeg-devel,v5,4/4] all: Rewrite documentation for contexts

diff --git a/libavcodec/aac/aacdec.h b/libavcodec/aac/aacdec.h
index eed53c6c96..87a834797d 100644
--- a/libavcodec/aac/aacdec.h
+++ b/libavcodec/aac/aacdec.h
@@ -253,7 +253,7 @@  typedef struct AACDecDSP {
 } AACDecDSP;
 
 /**
- * main AAC decoding context
+ * Context for decoding AAC
  */
 struct AACDecContext {
     const struct AVClass  *class;
diff --git a/libavcodec/aacenc.h b/libavcodec/aacenc.h
index d07960620e..3e710c7fac 100644
--- a/libavcodec/aacenc.h
+++ b/libavcodec/aacenc.h
@@ -207,7 +207,7 @@  typedef struct AACPCEInfo {
 } AACPCEInfo;
 
 /**
- * AAC encoder context
+ * Context for encoding AAC
  */
 typedef struct AACEncContext {
     AVClass *av_class;
diff --git a/libavcodec/ac3enc.h b/libavcodec/ac3enc.h
index 5e98ad188b..e5abe0a856 100644
--- a/libavcodec/ac3enc.h
+++ b/libavcodec/ac3enc.h
@@ -153,7 +153,7 @@  typedef struct AC3Block {
 struct PutBitContext;
 
 /**
- * AC-3 encoder private context.
+ * Private context for encoding AC-3
  */
 typedef struct AC3EncodeContext {
     AVClass *av_class;                      ///< AVClass used for AVOption
diff --git a/libavcodec/amfenc.h b/libavcodec/amfenc.h
index 2dbd378ef8..184897beeb 100644
--- a/libavcodec/amfenc.h
+++ b/libavcodec/amfenc.h
@@ -43,7 +43,7 @@  typedef struct AmfTraceWriter {
 } AmfTraceWriter;
 
 /**
-* AMF encoder context
+* Context for encoding AMF
 */
 
 typedef struct AmfContext {
diff --git a/libavcodec/atrac.h b/libavcodec/atrac.h
index 05208bbee6..e760f0384d 100644
--- a/libavcodec/atrac.h
+++ b/libavcodec/atrac.h
@@ -39,7 +39,7 @@  typedef struct AtracGainInfo {
 } AtracGainInfo;
 
 /**
- *  Gain compensation context structure.
+ *  Context for gain compensation
  */
 typedef struct AtracGCContext {
     float   gain_tab1[16];  ///< gain compensation level table
diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index abc00ab394..2fed4757ed 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.
+ * 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 ee5fdd48d2..fadcfc5d47 100644
--- a/libavcodec/bsf.h
+++ b/libavcodec/bsf.h
@@ -56,7 +56,7 @@ 
  */
 
 /**
- * The bitstream filter state.
+ * Context for bitstream filtering
  *
  * 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..c074dd11ec 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.
+ * Context for coded bitstream operations
  */
 typedef struct CodedBitstreamContext {
     /**
diff --git a/libavcodec/d3d11va.h b/libavcodec/d3d11va.h
index 686974b083..5ffee2b3be 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.
+ * 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 43f049a609..49af9513b0 100644
--- a/libavcodec/mediacodec.h
+++ b/libavcodec/mediacodec.h
@@ -26,8 +26,8 @@ 
 #include "libavcodec/avcodec.h"
 
 /**
- * This structure holds a reference to a android/view/Surface object that will
- * be used as output by the decoder.
+ * Context for the android/view/Surface object that will
+ * be used as output by the decoder
  *
  * @see
  * - @ref Context
diff --git a/libavcodec/pthread_frame.c b/libavcodec/pthread_frame.c
index 982e4a64c5..c462159022 100644
--- a/libavcodec/pthread_frame.c
+++ b/libavcodec/pthread_frame.c
@@ -69,7 +69,7 @@  typedef struct ThreadFrameProgress {
 } ThreadFrameProgress;
 
 /**
- * Context used by codec threads and stored in their AVCodecInternal thread_ctx.
+ * Context used by codec threads and allocated as AVCodecInternal.thread_ctx
  */
 typedef struct PerThreadContext {
     struct FrameThreadContext *parent;
@@ -113,7 +113,7 @@  typedef struct PerThreadContext {
 } PerThreadContext;
 
 /**
- * Context stored in the client AVCodecInternal thread_ctx.
+ * Context allocated as AVCodecInternal.thread_ctx
  */
 typedef struct FrameThreadContext {
     PerThreadContext *threads;     ///< The contexts for each thread.
diff --git a/libavcodec/qsv.h b/libavcodec/qsv.h
index 8ab93af6b6..9d36197fbf 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
+ * 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..ea0760776c 100644
--- a/libavcodec/sbr.h
+++ b/libavcodec/sbr.h
@@ -116,7 +116,7 @@  typedef struct SBRData {
 typedef struct SpectralBandReplication SpectralBandReplication;
 
 /**
- * aacsbr functions pointers
+ * Context for aacsbr functions
  */
 typedef struct AACSBRContext {
     int (*sbr_lf_gen)(SpectralBandReplication *sbr,
diff --git a/libavcodec/vdpau.h b/libavcodec/vdpau.h
index 934c96b88c..e20f37ef2a 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
- * the client video application.
+ * 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 81d90d63b6..dfc5c1a5a5 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.
+ * 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 25ccd80433..15aaba6ea2 100644
--- a/libavfilter/avfilter.h
+++ b/libavfilter/avfilter.h
@@ -404,7 +404,7 @@  unsigned avfilter_filter_pad_count(const AVFilter *filter, int is_output);
 #define AVFILTER_THREAD_SLICE (1 << 0)
 
 /**
- * An instance of a filter
+ * Context for a filter
  *
  * @see
  * - @ref Context
diff --git a/libavformat/avformat.h b/libavformat/avformat.h
index 18f20f0bb0..d8abab56d8 100644
--- a/libavformat/avformat.h
+++ b/libavformat/avformat.h
@@ -1241,7 +1241,8 @@  enum AVDurationEstimationMethod {
 };
 
 /**
- * Format I/O context.
+ * Context for format I/O
+ *
  * 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 d68f912a2f..bf017f1338 100644
--- a/libavformat/avio.h
+++ b/libavformat/avio.h
@@ -146,7 +146,8 @@  enum AVIODataMarkerType {
 };
 
 /**
- * Bytestream IO Context.
+ * Context for bytestream I/O
+ *
  * 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/audio_fifo.h b/libavutil/audio_fifo.h
index 6fdb114af8..ab56ef69f5 100644
--- a/libavutil/audio_fifo.h
+++ b/libavutil/audio_fifo.h
@@ -39,7 +39,7 @@ 
  */
 
 /**
- * Context for an Audio FIFO Buffer.
+ * Context for an Audio FIFO Buffer
  *
  * - Operates at the sample level rather than the byte level.
  * - Supports multiple channels with either planar or packed sample format.
diff --git a/libavutil/hwcontext.h b/libavutil/hwcontext.h
index 6bbb96fcd6..18d25a644c 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.
+ * 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
@@ -106,9 +107,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.
+ * 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 0db5a69f0a..bb380d5450 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
+ * Context allocated as AVHWDeviceContext.hwctx
  *
  * @see
  * - @ref Context
diff --git a/libavutil/hwcontext_d3d11va.h b/libavutil/hwcontext_d3d11va.h
index 5b7763e73f..ce07f84450 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
+ * Context allocated as AVHWDeviceContext.hwctx
  *
  * @see
  * - @ref Context
@@ -129,7 +129,7 @@  typedef struct AVD3D11FrameDescriptor {
 } AVD3D11FrameDescriptor;
 
 /**
- * This struct is allocated as AVHWFramesContext.hwctx
+ * Context allocated as AVHWFramesContext.hwctx
  *
  * @see
  * - @ref Context
diff --git a/libavutil/hwcontext_d3d12va.h b/libavutil/hwcontext_d3d12va.h
index 63281aa835..f741fc00e8 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 Context allocated as AVHWDeviceContext.hwctx
  *
  * @see
  * - @ref Context
@@ -80,7 +80,7 @@  typedef struct AVD3D12VADeviceContext {
 } AVD3D12VADeviceContext;
 
 /**
- * @brief This struct is used to sync d3d12 execution
+ * @brief Context for syncing d3d12 execution
  *
  * @see
  * - @ref Context
@@ -124,7 +124,7 @@  typedef struct AVD3D12VAFrame {
 } AVD3D12VAFrame;
 
 /**
- * @brief This struct is allocated as AVHWFramesContext.hwctx
+ * @brief Context allocated as AVHWFramesContext.hwctx
  *
  * @see
  * - @ref Context
diff --git a/libavutil/hwcontext_drm.h b/libavutil/hwcontext_drm.h
index eb0b6e734a..f8aa75c5cf 100644
--- a/libavutil/hwcontext_drm.h
+++ b/libavutil/hwcontext_drm.h
@@ -152,7 +152,7 @@  typedef struct AVDRMFrameDescriptor {
 /**
  * DRM device.
  *
- * Allocated as AVHWDeviceContext.hwctx.
+ * Context allocated as AVHWDeviceContext.hwctx
  *
  * @see
  * - @ref Context
diff --git a/libavutil/hwcontext_dxva2.h b/libavutil/hwcontext_dxva2.h
index 3accd8d070..a2320ea18a 100644
--- a/libavutil/hwcontext_dxva2.h
+++ b/libavutil/hwcontext_dxva2.h
@@ -34,7 +34,7 @@ 
 #include <dxva2api.h>
 
 /**
- * This struct is allocated as AVHWDeviceContext.hwctx
+ * Context allocated as AVHWDeviceContext.hwctx
  *
  * @see
  * - @ref Context
@@ -44,7 +44,7 @@  typedef struct AVDXVA2DeviceContext {
 } AVDXVA2DeviceContext;
 
 /**
- * This struct is allocated as AVHWFramesContext.hwctx
+ * Context allocated as AVHWFramesContext.hwctx
  *
  * @see
  * - @ref Context
diff --git a/libavutil/hwcontext_mediacodec.h b/libavutil/hwcontext_mediacodec.h
index 77d7d4e3a5..ada61fa61e 100644
--- a/libavutil/hwcontext_mediacodec.h
+++ b/libavutil/hwcontext_mediacodec.h
@@ -22,7 +22,7 @@ 
 /**
  * MediaCodec details.
  *
- * Allocated as AVHWDeviceContext.hwctx
+ * Context allocated as AVHWDeviceContext.hwctx
  *
  * @see
  * - @ref Context
diff --git a/libavutil/hwcontext_opencl.h b/libavutil/hwcontext_opencl.h
index 4c184484c9..0c3ef04fc6 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
+ * Context allocated as AVHWDeviceContext.hwctx
  *
  * @see
  * - @ref Context
@@ -87,7 +87,7 @@  typedef struct AVOpenCLDeviceContext {
 /**
  * OpenCL-specific data associated with a frame pool.
  *
- * Allocated as AVHWFramesContext.hwctx.
+ * Context allocated as AVHWFramesContext.hwctx
  *
  * @see
  * - @ref Context
diff --git a/libavutil/hwcontext_qsv.h b/libavutil/hwcontext_qsv.h
index b4a84c9893..afdddbce0e 100644
--- a/libavutil/hwcontext_qsv.h
+++ b/libavutil/hwcontext_qsv.h
@@ -30,7 +30,7 @@ 
  */
 
 /**
- * This struct is allocated as AVHWDeviceContext.hwctx
+ * Context allocated as AVHWDeviceContext.hwctx
  *
  * @see
  * - @ref Context
@@ -51,7 +51,7 @@  typedef struct AVQSVDeviceContext {
 } AVQSVDeviceContext;
 
 /**
- * This struct is allocated as AVHWFramesContext.hwctx
+ * Context allocated as AVHWFramesContext.hwctx
  *
  * @see
  * - @ref Context
diff --git a/libavutil/hwcontext_vaapi.h b/libavutil/hwcontext_vaapi.h
index 02399ff7dc..a6c1b25415 100644
--- a/libavutil/hwcontext_vaapi.h
+++ b/libavutil/hwcontext_vaapi.h
@@ -63,7 +63,7 @@  enum {
 /**
  * VAAPI connection details.
  *
- * Allocated as AVHWDeviceContext.hwctx
+ * Context allocated as AVHWDeviceContext.hwctx
  *
  * @see
  * - @ref Context
@@ -86,7 +86,7 @@  typedef struct AVVAAPIDeviceContext {
 /**
  * VAAPI-specific data associated with a frame pool.
  *
- * Allocated as AVHWFramesContext.hwctx.
+ * Context allocated as AVHWFramesContext.hwctx
  *
  * @see
  * - @ref Context
diff --git a/libavutil/hwcontext_vdpau.h b/libavutil/hwcontext_vdpau.h
index 051af42dfc..a2e6fcf5ba 100644
--- a/libavutil/hwcontext_vdpau.h
+++ b/libavutil/hwcontext_vdpau.h
@@ -30,7 +30,7 @@ 
  */
 
 /**
- * This struct is allocated as AVHWDeviceContext.hwctx
+ * Context allocated as AVHWDeviceContext.hwctx
  *
  * @see
  * - @ref Context
diff --git a/libavutil/hwcontext_vulkan.h b/libavutil/hwcontext_vulkan.h
index 6dfe4badfe..3766546100 100644
--- a/libavutil/hwcontext_vulkan.h
+++ b/libavutil/hwcontext_vulkan.h
@@ -39,7 +39,8 @@  typedef struct AVVkFrame AVVkFrame;
  */
 
 /**
- * Main Vulkan context, allocated as AVHWDeviceContext.hwctx.
+ * Context for Vulkan, allocated as AVHWDeviceContext.hwctx
+ *
  * All of these can be set before init to change what the context uses
  *
  * @see
@@ -175,7 +176,7 @@  typedef enum AVVkFrameFlags {
 } AVVkFrameFlags;
 
 /**
- * Allocated as AVHWFramesContext.hwctx, used to set pool-specific options
+ * Context allocated as AVHWFramesContext.hwctx, used to set pool-specific options
  *
  * @see
  * - @ref Context
diff --git a/libavutil/lfg.h b/libavutil/lfg.h
index 4e420b0e16..4ee7834fe4 100644
--- a/libavutil/lfg.h
+++ b/libavutil/lfg.h
@@ -25,7 +25,8 @@ 
 #include <stdint.h>
 
 /**
- * Context structure for the Lagged Fibonacci PRNG.
+ * Context structure for the Lagged Fibonacci PRNG
+ *
  * The exact layout, types and content of this struct may change and should
  * not be accessed directly. Only its `sizeof()` is guaranteed to stay the same
  * to allow easy instanciation.