add some explanatory comments

src/libutil/error.cc

@@ -152,12 +152,14 @@ void printErrorInfo(ErrorInfo &einfo)
 
   // lines of code.
   if (einfo.nixCode.has_value())
+  {
     printCodeLines(prefix, *einfo.nixCode);
+    cout << prefix << endl;
+  }
 
   // hint
   if (einfo.hint.has_value()) 
   {
-    cout << prefix << endl;
     cout << prefix << *einfo.hint << endl;
     cout << prefix << endl;
   }

src/libutil/error.hh

@@ -257,6 +257,7 @@ typedef AddName<
         AddDescription<
         AddHint<
         EIError>>> ProgramError;
+
 typedef AddName<
         AddDescription<
         AddHint<
@@ -270,6 +271,7 @@ typedef AddName<
         AddLOC<
         AddHint<
         EIError>>>>>>> NixLangError;
+
 typedef AddName<
         AddDescription<
         AddNixFile<

tests/errors/main.cc

@@ -8,26 +8,43 @@ using std::nullopt;
 using std::cout;
 using std::endl;
 
+
 int main() 
 {
   using namespace nix; 
 
+  // In each program where errors occur, this has to be set.
   ErrorInfo::programName = optional("error-test");
 
-  printErrorInfo(ProgramError()
+  // There are currently four error types - 
+  // 			ProgramError, ProgramWarning, NixLangError, NixLangWarning.
+  // Each error type is created with a specific sequence of builder functions.
+  // Unlike with a constructor, each parameter is clearly named.
+  // If the sequence of function calls isn't followed, then there's a type error.
+  // This should make for a consistent look in the code when errors are created.
+
+  // ProgramError takes name, description, and an optional hint.
+  printErrorInfo(
+    ProgramError()
       .name("name")
       .description("error description")
       .nohint()
       );
 
-  printErrorInfo(ProgramWarning()
+  // ProgramWarning takes name, description, and an optional hint.
+  // The hint is in the form of a hintfmt class, which wraps boost::format(), and 
+  // makes all the substituted text yellow.
+  printErrorInfo(
+    ProgramWarning()
       .name("warning name")
       .description("warning description")
-                .nohint()
+      .hint(hintfmt("there was a %1%") % "warning") // 'warning' will be yellow.
       );
 
-
+  // NixLangWarning adds nix file, line number, column range, and the lines of code 
-  printErrorInfo(NixLangWarning()
+  // where a warning occurred.
+  printErrorInfo(
+    NixLangWarning()
       .name("warning name")
       .description("warning description")
       .nixFile("myfile.nix")
@@ -39,7 +56,9 @@ int main()
       .hint(hintfmt("this hint has %1% templated %2%!!") % "yellow" % "values")
       );
 
-  printErrorInfo(NixLangError()
+  // NixLangError is just the same as NixLangWarning, except for the Error flag.
+  printErrorInfo(
+    NixLangError()
       .name("error name")
       .description("error description")
       .nixFile("myfile.nix")