Add code generation "warnings"

Add some comments to the tops of option.h and options.h that describe
how they are processed by make_option_enum.py and make_options.py. This
will serve both as some minimal documentation for those tools, and also
a warning against making changes to those headers that would break said
tools.

src/option.h

@@ -11,6 +11,17 @@
 #ifndef OPTION_H_INCLUDED
 #define OPTION_H_INCLUDED
 
+/* NOTE:
+ * This file is processed by make_option_enum.py, which parses any 'enum class'
+ * it finds, as well as the special macros UNC_OPTVAL_ALIAS and UNC_OPTVALS.
+ *
+ * The '// <PREFIX>' comment after an 'enum class' tells the script to generate
+ * aliases for the enum values using the prefix that is given in the '<>'s.
+ * Don't remove or alter these.
+ */
+
+#include "enum_flags.h"
+
 #include <vector>
 #include <string>
 

src/options.h

@@ -11,6 +11,24 @@
 #ifndef OPTIONS_H_INCLUDED
 #define OPTIONS_H_INCLUDED
 
+/* NOTE:
+ * This file is processed by make_options.py, and must conform to a particular
+ * format. Option groups are marked by '//begin ' (in upper case; this example
+ * is lower case to prevent being considered a region marker for code folding)
+ * followed by the group description. Options consist of two lines of
+ * declaration preceded by one or more lines of C++ comments. The comments form
+ * the option description and are taken verbatim, aside from stripping the
+ * leading '// '. Only comments immediately preceding an option declaration,
+ * with no blank lines, are taken as part of the description, so a blank line
+ * may be used to separate notations from a description.
+ *
+ * An option declaration is 'extern TYPE\nNAME;', optionally followed by
+ * ' // = VALUE' if the comment has a default value that is different from the
+ * default-constructed value type of the option. The 'VALUE' must be valid C++
+ * code, and is taken verbatim as an argument when creating the option's
+ * instantiation. Note also that the line break, as shown, is required.
+ */
+
 #include "option.h"
 #include "option_enum.h"