1 files changed, 19 insertions, 2 deletions
diff --git a/src/libutil/error.hh b/src/libutil/error.hh
index 0ca0c8b15..8a48fa105 100644
--- a/src/libutil/error.hh
+++ b/src/libutil/error.hh
@@ -22,6 +22,23 @@
 
 namespace nix {
 
+/* 
+
+This file defines two main structs/classes used in nix error handling.
+
+ErrorInfo provides a standard payload of error information, with conversion to string
+happening in the logger rather than at the call site.
+
+BaseError is the ancestor of nix specific exceptions (and Interrupted), and contains
+an ErrorInfo.
+
+ErrorInfo structs are sent to the logger as part of an exception, or directly with the
+logError or logWarning macros.
+
+See the error-demo.cc program for usage examples.
+
+*/
+
 typedef enum {
     lvlError = 0,
     lvlWarn,
@@ -32,6 +49,7 @@ typedef enum {
     lvlVomit
 } Verbosity;
 
+// ErrPos indicates the location of an error in a nix file.
 struct ErrPos {
     int line = 0;
     int column = 0;
@@ -42,6 +60,7 @@ struct ErrPos {
         return line != 0;
     }
 
+    // convert from the Pos struct, found in libexpr.
     template <class P>
     ErrPos& operator=(const P &pos)
     {
@@ -65,8 +84,6 @@ struct NixCode {
     std::optional<string> nextLineOfCode;
 };
 
-// -------------------------------------------------
-// ErrorInfo.
 struct ErrorInfo {
     Verbosity level;
     string name;