summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2019-07-12 04:07:04 +0200
committerwm4 <wm4@nowhere>2019-09-19 20:37:05 +0200
commit8576374faad7d56102c9a88bf1e6dffc71f307f5 (patch)
tree189a1d97e43b3a45e9476e97bf9e1d7fe299c1d5
parentb37a9685ad6714b6482cc276c06a2bf7cb0688bd (diff)
downloadmpv-8576374faad7d56102c9a88bf1e6dffc71f307f5.tar.bz2
mpv-8576374faad7d56102c9a88bf1e6dffc71f307f5.tar.xz
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.
-rw-r--r--options/m_config.c15
-rw-r--r--options/m_config.h39
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,