| Message ID | 20240523200116.740461-3-ffmpeg-devel@pileofstuff.org |
|---|---|
| State | New |
| Headers | show |
| Series | Explain what "context" means | expand |
| Context | Check | Description |
|---|---|---|
| yinshiyou/make_loongarch64 | success | Make finished |
| yinshiyou/make_fate_loongarch64 | success | Make fate finished |
| andriy/make_x86 | success | Make finished |
| andriy/make_fate_x86 | success | Make fate finished |
On date Thursday 2024-05-23 21:00:41 +0100, Andrew Sayers wrote: > --- > libavutil/log.h | 16 +++++++++++++--- > libavutil/opt.h | 17 ++++++++++++++--- > 2 files changed, 27 insertions(+), 6 deletions(-) > > diff --git a/libavutil/log.h b/libavutil/log.h > index ab7ceabe22..d599ab506e 100644 > --- a/libavutil/log.h > +++ b/libavutil/log.h > @@ -59,9 +59,19 @@ typedef enum { > struct AVOptionRanges; > > /** > - * Describe the class of an AVClass context structure. That is an > - * arbitrary struct of which the first field is a pointer to an > - * AVClass struct (e.g. AVCodecContext, AVFormatContext etc.). > + * Generic Logging and introspection facilities Looks mostly good to me but now I wonder if we are really confusing introspection with AVOptions (AVOptions adopt introspection but it's mostly about AVOptions themselves). So maybe we should replace "introspection" with something more concrete, such as: Generic logging and options facilities > + * > + * Logging and introspection functions expect to be passed structs > + * whose first member is a pointer-to-@ref AVClass. > + * > + * Structs that only use the logging facilities are often referred to as > + * "AVClass context structures", while those that use introspection facilities > + * are called "AVOptions-enabled structs". > + * > + * @see > + * * @ref lavu_log > + * * @ref avoptions > + * * @ref Context > */ > typedef struct AVClass { > /** > diff --git a/libavutil/opt.h b/libavutil/opt.h > index 07e27a9208..b14c120e36 100644 > --- a/libavutil/opt.h > +++ b/libavutil/opt.h > @@ -39,9 +39,16 @@ > * @defgroup avoptions AVOptions > * @ingroup lavu_data > * @{ > - * AVOptions provide a generic system to declare options on arbitrary structs > - * ("objects"). An option can have a help text, a type and a range of possible > - * values. Options may then be enumerated, read and written to. > + * > + * Generic introspection facilities for AVClass context structures ditto, more concrete with: Generic options facilities ... [...]
diff --git a/libavutil/log.h b/libavutil/log.h index ab7ceabe22..d599ab506e 100644 --- a/libavutil/log.h +++ b/libavutil/log.h @@ -59,9 +59,19 @@ typedef enum { struct AVOptionRanges; /** - * Describe the class of an AVClass context structure. That is an - * arbitrary struct of which the first field is a pointer to an - * AVClass struct (e.g. AVCodecContext, AVFormatContext etc.). + * Generic Logging and introspection facilities + * + * Logging and introspection functions expect to be passed structs + * whose first member is a pointer-to-@ref AVClass. + * + * Structs that only use the logging facilities are often referred to as + * "AVClass context structures", while those that use introspection facilities + * are called "AVOptions-enabled structs". + * + * @see + * * @ref lavu_log + * * @ref avoptions + * * @ref Context */ typedef struct AVClass { /** diff --git a/libavutil/opt.h b/libavutil/opt.h index 07e27a9208..b14c120e36 100644 --- a/libavutil/opt.h +++ b/libavutil/opt.h @@ -39,9 +39,16 @@ * @defgroup avoptions AVOptions * @ingroup lavu_data * @{ - * AVOptions provide a generic system to declare options on arbitrary structs - * ("objects"). An option can have a help text, a type and a range of possible - * values. Options may then be enumerated, read and written to. + * + * Generic introspection facilities for AVClass context structures + * + * Provides a generic system to declare and manage options on any struct + * whose first member is a pointer-to-@ref AVClass. Structs with private + * contexts can use that AVClass to return further @ref AVClass "AVClass"es + * that enable introspection of the private structs. + * + * Each option can have a help text, a type and a range of possible values. + * Options may be enumerated, read and written to. * * There are two modes of access to members of AVOption and its child structs. * One is called 'native access', and refers to access from the code that @@ -53,6 +60,10 @@ * question is allowed to access the field. This allows us to extend the * semantics of those fields without breaking API compatibility. * + * @see + * * @ref lavu_log + * * @ref Context + * * @section avoptions_scope Scope of AVOptions * * AVOptions is designed to support any set of multimedia configuration options