[FFmpeg-devel] [PATCH v5 2/4] lavu: Clarify relationship between AVClass, AVOption and context

[Stefano Sabatini]

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- at 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 ...

[...]