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,48 +8,67 @@ 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 - 
-                .name("name")
+  // 			ProgramError, ProgramWarning, NixLangError, NixLangWarning.
-                .description("error description")
+  // Each error type is created with a specific sequence of builder functions.
-                .nohint()
+  // 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.
 
-  printErrorInfo(ProgramWarning()
+  // ProgramError takes name, description, and an optional hint.
-                .name("warning name")
+  printErrorInfo(
-                .description("warning description")
+    ProgramError()
-                .nohint()
+      .name("name")
-                );
+      .description("error description")
+      .nohint()
+      );
 
+  // 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")
+      .hint(hintfmt("there was a %1%") % "warning") // 'warning' will be yellow.
+      );
 
-  printErrorInfo(NixLangWarning()
+  // NixLangWarning adds nix file, line number, column range, and the lines of code 
-                .name("warning name")
+  // where a warning occurred.
-                .description("warning description")
+  printErrorInfo(
-                .nixFile("myfile.nix")
+    NixLangWarning()
-                .lineNumber(40)
+      .name("warning name")
-                .columnRange(13,7)
+      .description("warning description")
-                .linesOfCode(nullopt
+      .nixFile("myfile.nix")
-                            ,"this is the problem line of code"
+      .lineNumber(40)
-                            ,nullopt)
+      .columnRange(13,7)
-                .hint(hintfmt("this hint has %1% templated %2%!!") % "yellow" % "values")
+      .linesOfCode(nullopt
-                );
+                  ,"this is the problem line of code"
+                  ,nullopt)
+      .hint(hintfmt("this hint has %1% templated %2%!!") % "yellow" % "values")
+      );
 
-  printErrorInfo(NixLangError()
+  // NixLangError is just the same as NixLangWarning, except for the Error flag.
-                .name("error name")
+  printErrorInfo(
-                .description("error description")
+    NixLangError()
-                .nixFile("myfile.nix")
+      .name("error name")
-                .lineNumber(40)
+      .description("error description")
-                .columnRange(13,7)
+      .nixFile("myfile.nix")
-                .linesOfCode(optional("previous line of code")
+      .lineNumber(40)
-                            ,"this is the problem line of code"
+      .columnRange(13,7)
-                            ,optional("next line of code"))
+      .linesOfCode(optional("previous line of code")
-                .hint(hintfmt("this hint has %1% templated %2%!!") % "yellow" % "values")
+                  ,"this is the problem line of code"
-                );
+                  ,optional("next line of code"))
+      .hint(hintfmt("this hint has %1% templated %2%!!") % "yellow" % "values")
+      );
 
   return 0;
 }