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

[Stefano Sabatini]

On date Wednesday 2024-05-15 16:54:20 +0100, Andrew Sayers wrote:
> ---
>  libavutil/log.h | 11 ++++++++---
>  libavutil/opt.h |  7 ++++---
>  2 files changed, 12 insertions(+), 6 deletions(-)
> 
> diff --git a/libavutil/log.h b/libavutil/log.h
> index ab7ceabe22..cfbf416679 100644
> --- a/libavutil/log.h
> +++ b/libavutil/log.h
> @@ -59,9 +59,14 @@ 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.).

> + * Metadata about an arbitrary data structure

The previous definition was circular, while this one is lacking
information (for example it is neglecting the logging facilities
provided by AVClass).

My take:
Provide access to generic logging and introspection facilities, used to
describe a class of structs.

An AVClass should be defined as the first element of the struct using
the AVClass facilities, so that functions operating on the AVClass
will work by providing the pointer to the structure.

Note: we might move the AVClass definition to its own file class.h.

> + *
> + * A @ref md_doc_2context "context struct" whose first member is a pointer
> + * to an AVClass object is called an "AVClass context structure"
> + * (e.g. AVCodecContext, AVFormatContext etc.).
> + *
> + * AVClass is often combined with @ref avoptions "AVOptions" to create
> + * "AVOptions-enabled structs" that can be easily configured by users.
>   */

>  typedef struct AVClass {
>      /**
> diff --git a/libavutil/opt.h b/libavutil/opt.h
> index 07e27a9208..e314e134c2 100644
> --- a/libavutil/opt.h
> +++ b/libavutil/opt.h
> @@ -39,9 +39,10 @@
>   * @defgroup avoptions AVOptions
>   * @ingroup lavu_data
>   * @{

> - * AVOptions provide a generic system to declare options on arbitrary structs
> - * ("objects").

This should be kept. In addition you can mention that it requires the
first element of the struct to be an AVClass (which is already
mentioned later in the text).

> An option can have a help text, a type and a range of possible
> - * values. Options may then be enumerated, read and written to.

> + * Builds on AVClass, adding a generic system to declare options.

> + *
> + * An option can have a help text, a type and a range of possible values.
> + * Options may then 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

[...]