(svn r24991) -Doc: Clarify comments regarding settings macros.

1 files changed, 17 insertions, 7 deletions

diff --git a/src/table/settings.h.preamble b/src/table/settings.h.preamble
index 75e93e26f..33345bb71 100644
--- a/src/table/settings.h.preamble
+++ b/src/table/settings.h.preamble
@@ -20,14 +20,24 @@ static size_t ConvertLandscape(const char *value);
 /**
  * Settings-macro usage:
  * The list might look daunting at first, but is in general easy to understand.
- * We have two types of list:
+ * The macros can be grouped depending on where the config variable is
+ * stored:
  * 1. SDTG_something
- * 2. SDT_something
- * The 'G' stands for global, so this is the one you will use for a
- * SettingDescGlobVarList section meaning global variables. The other uses a
- * Base/Offset and runtime variable selection mechanism, known from the saveload
- * convention (it also has global so it should not be hard).
- * Now there are a lot of types. Easy ones are:
+ *    These are for global variables, so this is the one you will use
+ *    for a #SettingDescGlobVarList section. Here 'var' refers to a
+ *    global variable.
+ * 2. SDTC_something
+ *    These are for client-only variables. Here the 'var' refers to an
+ *    entry inside _settings_client.
+ * 3. SDT_something
+ *    Thse are for members in the struct described by the current
+ *    #SettingDesc list / .ini file.  Here, 'base' specifies type of the
+ *    struct while 'var' points out the member of the struct (the actual
+ *    struct to store it in is implicitely defined by the #SettingDesc
+ *    list / .ini file preamble the entry is in).
+ *
+ * The something part defines the type of variable to store. There are a
+ * lot of types. Easy ones are:
  * - VAR:  any number type, 'type' field specifies what number. eg int8 or uint32
  * - BOOL: a boolean number type
  * - STR:  a string or character. 'type' field specifies what string. Normal, string, or quoted