[FFmpeg-devel] [PATCH 1/5] lavu/class: improve AVClass doxy

[Anton Khirnov]

---
 libavutil/log.h | 43 +++++++++++++++++++++++++++----------------
 1 file changed, 27 insertions(+), 16 deletions(-)

diff --git a/libavutil/log.h b/libavutil/log.h
index ab7ceabe22..c6b47cc054 100644
--- a/libavutil/log.h
+++ b/libavutil/log.h
@@ -77,7 +77,9 @@ typedef struct AVClass {
     const char* (*item_name)(void* ctx);
 
     /**
-     * a pointer to the first option specified in the class if any or NULL
+     * An array of options for the structure or NULL.
+     * When non-NULL, the array must be terminated by an option with a NULL
+     * name.
      *
      * @see av_set_default_options()
      */
@@ -85,43 +87,50 @@ typedef struct AVClass {
 
     /**
      * LIBAVUTIL_VERSION with which this structure was created.
-     * This is used to allow fields to be added without requiring major
-     * version bumps everywhere.
+     * This is used to allow fields to be added to AVClass without requiring
+     * major version bumps everywhere.
      */
 
     int version;
 
     /**
-     * Offset in the structure where log_level_offset is stored.
-     * 0 means there is no such variable
+     * Offset in the structure where the log level offset is stored. The log
+     * level offset is added to the log level for logging with this object as
+     * the context.
+     *
+     * 0 means there is no such variable.
      */
     int log_level_offset_offset;
 
     /**
      * Offset in the structure where a pointer to the parent context for
      * logging is stored. For example a decoder could pass its AVCodecContext
-     * to eval as such a parent context, which an av_log() implementation
+     * to eval as such a parent context, which an ::av_log() implementation
      * could then leverage to display the parent context.
-     * The offset can be NULL.
+     *
+     * When the pointer is NULL, or this offset is zero, the object is assumed
+     * to have no parent.
      */
     int parent_log_context_offset;
 
     /**
-     * Category used for visualization (like color)
-     * This is only set if the category is equal for all objects using this class.
-     * available since version (51 << 16 | 56 << 8 | 100)
+     * Category used for visualization (like color).
+     *
+     * Only used when ::get_category() is NULL. Use this field when all
+     * instances of this class have the same category, use ::get_category()
+     * otherwise.
      */
     AVClassCategory category;
 
     /**
-     * Callback to return the category.
-     * available since version (51 << 16 | 59 << 8 | 100)
+     * Callback to return the instance category. Use this callback when
+     * different instances of this class may have different categories,
+     * ::category otherwise.
      */
     AVClassCategory (*get_category)(void* ctx);
 
     /**
      * Callback to return the supported/allowed ranges.
-     * available since version (52.12)
      */
     int (*query_ranges)(struct AVOptionRanges **, void *obj, const char *key, int flags);
 
@@ -139,9 +148,11 @@ typedef struct AVClass {
      * @return AVClass for the next AVOptions-enabled child or NULL if there are
      *         no more such children.
      *
-     * @note The difference between child_next and this is that child_next
-     *       iterates over _already existing_ objects, while child_class_iterate
-     *       iterates over _all possible_ children.
+     * @note The difference between ::child_next() and ::child_class_iterate()
+     *       is that ::child_next() iterates over _actual_ children of an
+     *       _existing_ object instance, while ::child_class_iterate() iterates
+     *       over the classes of all _potential_ children of any possible
+     *       instance of this class.
      */
     const struct AVClass* (*child_class_iterate)(void **iter);
 } AVClass;
-- 
2.43.0