[FFmpeg-devel] [PATCH] avutil/opt: Say more often that AV_OPT_SEARCH_CHILDREN searches children first

[Andrew Sayers]

This behaviour is already mentioned in the documentation for
AV_OPT_SEARCH_CHILDREN itself, but that's quite easy to miss.

Knowing that child options *override* parent ones is useful for users,
so it's worth mentioning in all the places they would look.

av_opt_find() had a note that av_opt_find2() was missing.
Assume that wasn't deliberate, and copy it over.
---
 libavutil/opt.h | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/libavutil/opt.h b/libavutil/opt.h
index 07e27a9208..24b807ec66 100644
--- a/libavutil/opt.h
+++ b/libavutil/opt.h
@@ -211,7 +211,7 @@
  *
  * The situation is more complicated with nesting. An AVOptions-enabled struct
  * may have AVOptions-enabled children. Passing the AV_OPT_SEARCH_CHILDREN flag
- * to av_opt_find() will make the function search children recursively.
+ * to av_opt_find() will make the function recursively search children first.
  *
  * For enumerating there are basically two cases. The first is when you want to
  * get all options that may potentially exist on the struct and its children
@@ -570,10 +570,11 @@ const AVClass *av_opt_child_class_iterate(const AVClass *parent, void **iter);
  * @return A pointer to the option found, or NULL if no option
  *         was found.
  *
- * @note Options found with AV_OPT_SEARCH_CHILDREN flag may not be settable
- * directly with av_opt_set(). Use special calls which take an options
- * AVDictionary (e.g. avformat_open_input()) to set options found with this
- * flag.
+ * @note If AV_OPT_SEARCH_CHILDREN is set, this function will return an
+ * option from the first matching child class, or the specified class if
+ * no child matches.  Options from child classes may not be settable directly
+ * with av_opt_set(), so use special calls which take an options AVDictionary
+ * (e.g. avformat_open_input()) to set options found with this flag.
  */
 const AVOption *av_opt_find(void *obj, const char *name, const char *unit,
                             int opt_flags, int search_flags);
@@ -598,6 +599,12 @@ const AVOption *av_opt_find(void *obj, const char *name, const char *unit,
  *
  * @return A pointer to the option found, or NULL if no option
  *         was found.
+ *
+ * @note If AV_OPT_SEARCH_CHILDREN is set, this function will return an
+ * option from the first matching child class, or the specified class if
+ * no child matches.  Options from child classes may not be settable directly
+ * with av_opt_set(), so use special calls which take an options AVDictionary
+ * (e.g. avformat_open_input()) to set options found with this flag.
  */
 const AVOption *av_opt_find2(void *obj, const char *name, const char *unit,
                              int opt_flags, int search_flags, void **target_obj);
@@ -780,7 +787,8 @@ int av_opt_copy(void *dest, const void *src);
  * key=value parameters. Values containing ':' special characters must be
  * escaped.
  * @param search_flags flags passed to av_opt_find2. I.e. if AV_OPT_SEARCH_CHILDREN
- * is passed here, then the option may be set on a child of obj.
+ * is passed here, av_opt_set() will set the first matching child if possible,
+ * or obj if no child matches.
  *
  * @return 0 if the value has been set, or an AVERROR code in case of
  * error:
-- 
2.43.0