[tor-commits] [tor/master] Revise documentation on CFLG_* flags

[dgoulet at torproject.org]

commit bbd40e690ee596af60fb38c5e89dec92f6091b1d
Author: Nick Mathewson <nickm at 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)