commit bbd40e690ee596af60fb38c5e89dec92f6091b1d Author: Nick Mathewson nickm@torproject.org Date: Thu Sep 5 11:48:52 2019 -0400

Revise documentation on CFLG_* flags --- src/lib/conf/conftypes.h | 46 ++++++++++++++++++++++++++++------------------ 1 file changed, 28 insertions(+), 18 deletions(-)

diff --git a/src/lib/conf/conftypes.h b/src/lib/conf/conftypes.h index 1f6120670..aabdfdce7 100644 --- a/src/lib/conf/conftypes.h +++ b/src/lib/conf/conftypes.h @@ -132,40 +132,50 @@ typedef struct struct_magic_decl_t { } struct_magic_decl_t;

/** - * Flag to indicate that an option is undumpable. An undumpable option is - * never saved to disk. + * Flag to indicate that an option or type is "undumpable". An + * undumpable option is never saved to disk. * - * For historical reasons it is prefixed with __ but not with ___. + * For historical reasons its name is usually is prefixed with __. **/ #define CFLG_NODUMP (1u<<0) /** - * Flag to indicate that an option is "invisible". An invisible option - * is always undumpable, and we don't tell the controller about it. - * For historical reasons it is prefixed with ___. + * Flag to indicate that an option or type is "unlisted". + * + * We don't tell the controller about unlisted options when it asks for a + * list of them. **/ #define CFLG_NOLIST (1u<<1) - /** - * Flag for var_type_def_t. - * Set iff a variable of this type can never be set directly by name. + * Flag to indicate that an option or type is "unsettable". + * + * An unsettable option can never be set directly by name. **/ #define CFLG_NOSET (1u<<2) /** - * Flag for var_type_def_t. - * Set iff a variable of this type is does not need to be copied when copying - * the structure that contains it. + * Flag to indicate that an option or type does not need to be copied when + * copying the structure that contains it. + * + * (Usually, if an option does not need to be copied, then either it contains + * no data, or the data that it does contain is completely contained within + * another option.) **/ #define CFLG_NOCOPY (1u<<3) /** - * Flag for var_type_def_t. - * Set iff a variable of this type does not need to be compared when comparing - * two objects that contain it. + * Flag to indicate that an option or type does not need to be compared + * when telling the controller about the differences between two + * configurations. + * + * (Usually, if an option does not need to be compared, then either it + * contains no data, or the data that it does contain is completely contained + * within another option.) **/ #define CFLG_NOCMP (1u<<4) /** - * Flag for var_type_def_t. - * Set iff a variable of this type can be set more than once without - * destroying older values. Such variables should implement "mark_fragile". + * Flag to indicate that an option or type should not be replaced when setting + * it. + * + * For most options, setting them replaces their old value. For some options, + * however, setting them appends to their old value. */ #define CFLG_NOREPLACE (1u<<5)