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(-) (limited to 'src/app/config/confparse.h') 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