History

lavu/class: improve AVClass doxy

Anton Khirnov committed 2 years ago

Commit 041d9921 parent 240c16b1 file · +27 −16Browse files

Unified · Split

libavutil/log.h+27−16
@@ -77,7 +77,9 @@ typedef struct AVClass { · 76 unmodified lines
7777 const char* (*item_name)(void* ctx);
7878
7979 /**
80− * a pointer to the first option specified in the class if any or NULL
80+ * An array of options for the structure or NULL.
81+ * When non-NULL, the array must be terminated by an option with a NULL
82+ * name.
8183 *
8284 * @see av_set_default_options()
8385 */
@@ -85,43 +87,50 @@ typedef struct AVClass { · 1 unmodified line
8587
8688 /**
8789 * LIBAVUTIL_VERSION with which this structure was created.
88− * This is used to allow fields to be added without requiring major
89− * version bumps everywhere.
90+ * This is used to allow fields to be added to AVClass without requiring
91+ * major version bumps everywhere.
9092 */
9193
9294 int version;
9395
9496 /**
95− * Offset in the structure where log_level_offset is stored.
96− * 0 means there is no such variable
97+ * Offset in the structure where the log level offset is stored. The log
98+ * level offset is an int added to the log level for logging with this
99+ * object as the context.
100+ *
101+ * 0 means there is no such variable.
97102 */
98103 int log_level_offset_offset;
99104
100105 /**
101106 * Offset in the structure where a pointer to the parent context for
102107 * logging is stored. For example a decoder could pass its AVCodecContext
103− * to eval as such a parent context, which an av_log() implementation
108+ * to eval as such a parent context, which an ::av_log() implementation
104109 * could then leverage to display the parent context.
105− * The offset can be NULL.
110+ *
111+ * When the pointer is NULL, or this offset is zero, the object is assumed
112+ * to have no parent.
106113 */
107114 int parent_log_context_offset;
108115
109116 /**
110− * Category used for visualization (like color)
111− * This is only set if the category is equal for all objects using this class.
112− * available since version (51 << 16 | 56 << 8 | 100)
117+ * Category used for visualization (like color).
118+ *
119+ * Only used when ::get_category() is NULL. Use this field when all
120+ * instances of this class have the same category, use ::get_category()
121+ * otherwise.
113122 */
114123 AVClassCategory category;
115124
116125 /**
117− * Callback to return the category.
118− * available since version (51 << 16 | 59 << 8 | 100)
126+ * Callback to return the instance category. Use this callback when
127+ * different instances of this class may have different categories,
128+ * ::category otherwise.
119129 */
120130 AVClassCategory (*get_category)(void* ctx);
121131
122132 /**
123133 * Callback to return the supported/allowed ranges.
124− * available since version (52.12)
125134 */
126135 int (*query_ranges)(struct AVOptionRanges **, void *obj, const char *key, int flags);
127136
@@ -139,9 +148,11 @@ typedef struct AVClass { · 11 unmodified lines
139148 * @return AVClass for the next AVOptions-enabled child or NULL if there are
140149 * no more such children.
141150 *
142− * @note The difference between child_next and this is that child_next
143− * iterates over _already existing_ objects, while child_class_iterate
144− * iterates over _all possible_ children.
151+ * @note The difference between ::child_next() and ::child_class_iterate()
152+ * is that ::child_next() iterates over _actual_ children of an
153+ * _existing_ object instance, while ::child_class_iterate() iterates
154+ * over the classes of all _potential_ children of any possible
155+ * instance of this class.
145156 */
146157 const struct AVClass* (*child_class_iterate)(void **iter);
147158 } AVClass;

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t