Add documentation to irep_ids

src/util/irep_ids.def

@@ -1,3 +1,6 @@
+/// \file List of irep id names and values.
+/// For an explanation of how this works, see irep_ids.h.
+
 IREP_ID_TWO(empty_string, )
 IREP_ID_ONE(let)
 IREP_ID_ONE(nil)

src/util/irep_ids.h

@@ -15,6 +15,17 @@ Author: Reuben Thomas, reuben.thomas@me.com
 #include "dstring.h"
 #endif
 
+/// \file The irep_ids are generated using a technique called
+/// [X-macros](https://en.wikipedia.org/wiki/X_Macro).
+/// The ids are defined in the file irep_ids.def, using a pair of macros
+/// `IREP_ID_ONE` and `IREP_ID_TWO`.
+/// Definitions of the form `IREP_ID_ONE(param)` will be converted into a
+/// const extern irep_idt with the variable name `ID_param` and the string
+/// value `"param"`.
+/// Definitions of the form `IREP_ID_TWO(param, contents)` will be converted
+/// into a const extern irep_idt with the variable name `ID_param` and the
+/// string value `"contents"`.
+
 enum class idt:unsigned
 {
 #define IREP_ID_ONE(the_id) id_##the_id,