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

[Andrew Sayers]

---
 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
+ *
+ * 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
+ *
+ * Provides a generic system to declare and manage options on any struct
+ * whose first member is a pointer-to- at 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
-- 
2.43.0