From 8576374faad7d56102c9a88bf1e6dffc71f307f5 Mon Sep 17 00:00:00 2001 From: wm4 Date: Fri, 12 Jul 2019 04:07:04 +0200 Subject: m_config: add/move some comments Move the comments documenting exported functions to the header. It looks like the header is the preferred place for that (although I don't really appreciate headers where you lose the overview because of all the documentation comments). Add comments to some undocumented prototypes. --- options/m_config.c | 15 --------------- options/m_config.h | 39 +++++++++++++++++++++++++++++++++------ 2 files changed, 33 insertions(+), 21 deletions(-) diff --git a/options/m_config.c b/options/m_config.c index 92bb47d789..e461602023 100644 --- a/options/m_config.c +++ b/options/m_config.c @@ -348,7 +348,6 @@ static struct m_config *m_config_from_obj_desc(void *talloc_ctx, return c; } -// Like m_config_from_obj_desc(), but don't allocate option struct. struct m_config *m_config_from_obj_desc_noalloc(void *talloc_ctx, struct mp_log *log, struct m_obj_desc *desc) @@ -370,11 +369,6 @@ static const struct m_config_group *find_group(struct mpv_global *global, return NULL; } -// Allocate a priv struct that is backed by global options (like AOs and VOs, -// anything that uses m_obj_list.use_global_options == true). -// The result contains a snapshot of the current option values of desc->options. -// For convenience, desc->options can be NULL; then priv struct is allocated -// with just zero (or priv_defaults if set). void *m_config_group_from_desc(void *ta_parent, struct mp_log *log, struct mpv_global *global, struct m_obj_desc *desc, const char *name) { @@ -804,8 +798,6 @@ static int m_config_handle_special_options(struct m_config *config, return M_OPT_UNKNOWN; } -// Unlike m_config_set_option_raw() this does not go through the property layer -// via config.option_set_callback. int m_config_set_option_raw_direct(struct m_config *config, struct m_config_option *co, void *data, int flags) @@ -834,9 +826,6 @@ int m_config_set_option_raw_direct(struct m_config *config, return 0; } -// Similar to m_config_set_option_cli(), but set as data in its native format. -// This takes care of some details like sending change notifications. -// The type data points to is as in: co->opt int m_config_set_option_raw(struct m_config *config, struct m_config_option *co, void *data, int flags) { @@ -923,10 +912,6 @@ static struct m_config_option *m_config_mogrify_cli_opt(struct m_config *config, return NULL; } -// Set the named option to the given string. This is for command line and config -// file use only. -// flags: combination of M_SETOPT_* flags (0 for normal operation) -// Returns >= 0 on success, otherwise see OptionParserReturn. int m_config_set_option_cli(struct m_config *config, struct bstr name, struct bstr param, int flags) { diff --git a/options/m_config.h b/options/m_config.h index ac6966bb22..a640f43eef 100644 --- a/options/m_config.h +++ b/options/m_config.h @@ -118,14 +118,28 @@ struct m_config *m_config_new(void *talloc_ctx, struct mp_log *log, // mpv_global. Expected to be called at early init on the main m_config. void m_config_create_shadow(struct m_config *config); -struct m_config *m_config_from_obj_desc_noalloc(void *talloc_ctx, - struct mp_log *log, - struct m_obj_desc *desc); - +// Create a m_config for the given desc. This is for --af/--vf, which have +// different sub-options for every filter (represented by separate desc +// structs). +// args is an array of key/value pairs (args=[k0, v0, k1, v1, ..., NULL]). +// name/defaults is only needed for the legacy af-defaults/vf-defaults options. struct m_config *m_config_from_obj_desc_and_args(void *ta_parent, struct mp_log *log, struct mpv_global *global, struct m_obj_desc *desc, const char *name, struct m_obj_settings *defaults, char **args); +// Like m_config_from_obj_desc_and_args(), but don't allocate option the +// struct, i.e. m_config.optstruct==NULL. This is used by the sub-option +// parser (--af/--vf, to a lesser degree --ao/--vo) to check sub-option names +// and types. +struct m_config *m_config_from_obj_desc_noalloc(void *talloc_ctx, + struct mp_log *log, + struct m_obj_desc *desc); + +// Allocate a priv struct that is backed by global options (like AOs and VOs, +// anything that uses m_obj_list.use_global_options == true). +// The result contains a snapshot of the current option values of desc->options. +// For convenience, desc->options can be NULL; then priv struct is allocated +// with just zero (or priv_defaults if set). void *m_config_group_from_desc(void *ta_parent, struct mp_log *log, struct mpv_global *global, struct m_obj_desc *desc, const char *name); @@ -155,27 +169,40 @@ enum { // Flags for safe option setting during runtime. #define M_SETOPT_RUNTIME M_SETOPT_NO_FIXED +// Set the named option to the given string. This is for command line and config +// file use only. +// flags: combination of M_SETOPT_* flags (0 for normal operation) +// Returns >= 0 on success, otherwise see OptionParserReturn. int m_config_set_option_cli(struct m_config *config, struct bstr name, struct bstr param, int flags); +// Similar to m_config_set_option_cli(), but set as data in its native format. +// This takes care of some details like sending change notifications. +// The type data points to is as in: co->opt int m_config_set_option_raw(struct m_config *config, struct m_config_option *co, void *data, int flags); void m_config_mark_co_flags(struct m_config_option *co, int flags); +// Unlike m_config_set_option_raw() this does not go through the property layer +// via config.option_set_callback. int m_config_set_option_raw_direct(struct m_config *config, struct m_config_option *co, void *data, int flags); +// Convert the mpv_node to raw option data, then call m_config_set_option_raw(). struct mpv_node; int m_config_set_option_node(struct m_config *config, bstr name, struct mpv_node *data, int flags); -struct m_config_option *m_config_get_co_raw(const struct m_config *config, - struct bstr name); +// Return option descriptor. You shouldn't use this. struct m_config_option *m_config_get_co(const struct m_config *config, struct bstr name); +// Same as above, but does not resolve aliases or trigger warning messages. +struct m_config_option *m_config_get_co_raw(const struct m_config *config, + struct bstr name); +// Special uses only. Look away. int m_config_get_co_count(struct m_config *config); struct m_config_option *m_config_get_co_index(struct m_config *config, int index); const void *m_config_get_co_default(const struct m_config *config, -- cgit v1.2.3