diff --git a/src/util/irep_ids.def b/src/util/irep_ids.def
index 56153453d7c..92e3cf367f2 100644
--- a/src/util/irep_ids.def
+++ b/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)
diff --git a/src/util/irep_ids.h b/src/util/irep_ids.h
index 50fc06314b5..c456840ef5f 100644
--- a/src/util/irep_ids.h
+++ b/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,