From 577ea20b3a34ed61bc7a005e4105c63abad85d41 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Wed, 4 Sep 2019 13:41:53 -0400 Subject: Document configuration and abbreviation types. --- src/app/config/confparse.h | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/src/app/config/confparse.h b/src/app/config/confparse.h index b788e2cd1b..d628db503e 100644 --- a/src/app/config/confparse.h +++ b/src/app/config/confparse.h @@ -17,21 +17,38 @@ #include "lib/conf/confmacros.h" #include "lib/testsupport/testsupport.h" -/** An abbreviation for a configuration option allowed on the command line. */ +/** + * An abbreviation or alias for a configuration option. + **/ typedef struct config_abbrev_t { + /** The option name as abbreviated. Not case-sensitive. */ const char *abbreviated; + /** The full name of the option. Not case-sensitive. */ const char *full; + /** True if this abbreviation should only be allowed on the command line. */ int commandline_only; + /** True if we should warn whenever this abbreviation is used. */ int warn; } config_abbrev_t; +/** + * A note that a configuration option is deprecated, with an explanation why. + */ typedef struct config_deprecation_t { + /** The option that is deprecated. */ const char *name; + /** A user-facing string explaining why the option is deprecated. */ const char *why_deprecated; } config_deprecation_t; -/* Handy macro for declaring "In the config file or on the command line, - * you can abbreviate toks as tok". */ +/** + * Handy macro for declaring "In the config file or on the command line, you + * can abbreviate toks as tok". Used inside an array of + * config_abbrev_t. + * + * For example, to declare "NumCpu" as an abbreviation for "NumCPUs", + * you can say PLURAL(NumCpu). + **/ #define PLURAL(tok) { #tok, #tok "s", 0, 0 } /** Type of a callback to validate whether a given configuration is -- cgit v1.2.3-54-g00ecf From aeda598fd5935331e96975b91eb91bce21096f9b Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Wed, 4 Sep 2019 13:48:16 -0400 Subject: config_assign: Document CAL_* options. These were sort of described in config_assign() documentation, but not so well. --- src/app/config/confparse.h | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/src/app/config/confparse.h b/src/app/config/confparse.h index d628db503e..405200d692 100644 --- a/src/app/config/confparse.h +++ b/src/app/config/confparse.h @@ -113,8 +113,28 @@ struct smartlist_t *config_mgr_list_deprecated_vars(const config_mgr_t *mgr); /** A collection of managed configuration objects. */ typedef struct config_suite_t config_suite_t; +/** + * Flag for config_assign: if set, then "resetting" an option changes it to + * its default value, as specified in the config_var_t. Otherwise, + * "resetting" an option changes it to a type-dependent null value -- + * typically 0 or NULL. + * + * (An option is "reset" when it is set to an empty value, or as described in + * CAL_CLEAR_FIRST). + **/ #define CAL_USE_DEFAULTS (1u<<0) +/** + * Flag for config_assign: if set, then we reset every provided config + * option before we set it. + * + * For example, if this flag is not set, then passing a multi-line option to + * config_assign will cause any previous value to be extended. But if this + * flag is set, then a multi-line option will replace any previous value. + **/ #define CAL_CLEAR_FIRST (1u<<1) +/** + * Flag for config_assign: if set, we warn about deprecated options. + **/ #define CAL_WARN_DEPRECATIONS (1u<<2) void *config_new(const config_mgr_t *fmt); -- cgit v1.2.3-54-g00ecf From 39dd2e2aa826930bfe681d99c3e8374757ac511b Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Wed, 4 Sep 2019 13:54:26 -0400 Subject: Document validate_fn_t as it stands. Also document that it will be changed in a later branch. --- src/app/config/confparse.h | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/src/app/config/confparse.h b/src/app/config/confparse.h index 405200d692..baf60f07cd 100644 --- a/src/app/config/confparse.h +++ b/src/app/config/confparse.h @@ -51,10 +51,28 @@ typedef struct config_deprecation_t { **/ #define PLURAL(tok) { #tok, #tok "s", 0, 0 } -/** Type of a callback to validate whether a given configuration is - * well-formed and consistent. See options_trial_assign() for documentation - * of arguments. */ -typedef int (*validate_fn_t)(void*,void*,void*,int,char**); +/** + * Type of a callback to validate whether a given configuration is + * well-formed and consistent. + * + * The configuration to validate is passed as newval. The previous + * configuration, if any, is provided in oldval. The + * default_val argument receives a configuration object initialized + * with default values for all its fields. The from_setconf argument + * is true iff the input comes from a SETCONF controller command. + * + * On success, return 0. On failure, set *msg_out to a newly allocated + * error message, and return -1. + * + * REFACTORING NOTE: Currently, this callback type is only used from inside + * config_dump(); later in our refactoring, it will be cleaned up and used + * more generally. + */ +typedef int (*validate_fn_t)(void *oldval, + void *newval, + void *default_val, + int from_setconf, + char **msg_out); struct config_mgr_t; -- cgit v1.2.3-54-g00ecf From 39316da9b643583f52c1ff30bca7a07ea04cdba3 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Wed, 4 Sep 2019 14:01:32 -0400 Subject: Document return value of config_mgr_add_format(). --- src/app/config/confparse.c | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/app/config/confparse.c b/src/app/config/confparse.c index f20a361ba3..23a89ba627 100644 --- a/src/app/config/confparse.c +++ b/src/app/config/confparse.c @@ -203,6 +203,9 @@ config_mgr_register_fmt(config_mgr_t *mgr, /** * Add a new format to this configuration object. Asserts on failure. * + * Returns an internal "index" value used to identify this format within + * all of those formats contained in mgr. This index value + * should not generally be used outside of this module. **/ int config_mgr_add_format(config_mgr_t *mgr, -- cgit v1.2.3-54-g00ecf From 3db56aeeb8a59629690a05cd43565764a254d1e1 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Wed, 4 Sep 2019 14:01:43 -0400 Subject: Document warn_deprecated_option(). --- src/app/config/confparse.c | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/app/config/confparse.c b/src/app/config/confparse.c index 23a89ba627..b0ff4daa83 100644 --- a/src/app/config/confparse.c +++ b/src/app/config/confparse.c @@ -578,6 +578,10 @@ config_mark_lists_fragile(const config_mgr_t *mgr, void *options) } SMARTLIST_FOREACH_END(mv); } +/** + * Log a warning that declaring that the option called what + * is deprecated because of the reason in why. + **/ void warn_deprecated_option(const char *what, const char *why) { -- cgit v1.2.3-54-g00ecf From b3c28677159c26070f26909b3f4c2e00e50d7bff Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Wed, 4 Sep 2019 14:03:38 -0400 Subject: Document fields of struct_magic_decl_t. --- src/lib/conf/conftypes.h | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/lib/conf/conftypes.h b/src/lib/conf/conftypes.h index fabad97d0c..3db115204b 100644 --- a/src/lib/conf/conftypes.h +++ b/src/lib/conf/conftypes.h @@ -100,8 +100,12 @@ typedef struct struct_member_t { * that they have the correct type. */ typedef struct struct_magic_decl_t { + /** The name of the structure */ const char *typename; + /** A value used to recognize instances of this structure. */ uint32_t magic_val; + /** The location within the structure at which we expect to find + * magic_val. */ int magic_offset; } struct_magic_decl_t; -- cgit v1.2.3-54-g00ecf From eb909c4e433087b466e78d33af8eed47adcabf16 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Thu, 5 Sep 2019 07:57:36 -0400 Subject: config: note that some arguments are required. --- src/app/config/confparse.c | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/app/config/confparse.c b/src/app/config/confparse.c index b0ff4daa83..054d2addbd 100644 --- a/src/app/config/confparse.c +++ b/src/app/config/confparse.c @@ -581,6 +581,8 @@ config_mark_lists_fragile(const config_mgr_t *mgr, void *options) /** * Log a warning that declaring that the option called what * is deprecated because of the reason in why. + * + * (Both arguments must be non-NULL.) **/ void warn_deprecated_option(const char *what, const char *why) -- cgit v1.2.3-54-g00ecf