add some explanatory comments

3 files changed, 60 insertions, 37 deletions

diff --git a/src/libutil/error.cc b/src/libutil/error.cc
index c986affcc..5384248f8 100644
--- a/src/libutil/error.cc
+++ b/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;
   }
diff --git a/src/libutil/error.hh b/src/libutil/error.hh
index cd2b2832d..00539f06a 100644
--- a/src/libutil/error.hh
+++ b/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<
diff --git a/tests/errors/main.cc b/tests/errors/main.cc
index 101d44a7e..1aff5a016 100644
--- a/tests/errors/main.cc
+++ b/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()
-                .name("name")
-                .description("error description")
-                .nohint()
-                );
-
-  printErrorInfo(ProgramWarning()
-                .name("warning name")
-                .description("warning description")
-                .nohint()
-                );
-
-
-  printErrorInfo(NixLangWarning()
-                .name("warning name")
-                .description("warning description")
-                .nixFile("myfile.nix")
-                .lineNumber(40)
-                .columnRange(13,7)
-                .linesOfCode(nullopt
-                            ,"this is the problem line of code"
-                            ,nullopt)
-                .hint(hintfmt("this hint has %1% templated %2%!!") % "yellow" % "values")
-                );
-
-  printErrorInfo(NixLangError()
-                .name("error name")
-                .description("error description")
-                .nixFile("myfile.nix")
-                .lineNumber(40)
-                .columnRange(13,7)
-                .linesOfCode(optional("previous line of code")
-                            ,"this is the problem line of code"
-                            ,optional("next line of code"))
-                .hint(hintfmt("this hint has %1% templated %2%!!") % "yellow" % "values")
-                );
+  // 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()
+      );
+
+  // 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.
+      );
+
+  // NixLangWarning adds nix file, line number, column range, and the lines of code 
+  // where a warning occurred.
+  printErrorInfo(
+    NixLangWarning()
+      .name("warning name")
+      .description("warning description")
+      .nixFile("myfile.nix")
+      .lineNumber(40)
+      .columnRange(13,7)
+      .linesOfCode(nullopt
+                  ,"this is the problem line of code"
+                  ,nullopt)
+      .hint(hintfmt("this hint has %1% templated %2%!!") % "yellow" % "values")
+      );
+
+  // NixLangError is just the same as NixLangWarning, except for the Error flag.
+  printErrorInfo(
+    NixLangError()
+      .name("error name")
+      .description("error description")
+      .nixFile("myfile.nix")
+      .lineNumber(40)
+      .columnRange(13,7)
+      .linesOfCode(optional("previous line of code")
+                  ,"this is the problem line of code"
+                  ,optional("next line of code"))
+      .hint(hintfmt("this hint has %1% templated %2%!!") % "yellow" % "values")
+      );
 
   return 0;
 }