Added extensive doc comments to errors package

errors/doc.go

@@ -0,0 +1,5 @@
+// Package errors provides a location tracking and error formatting system.
+// It provides a way to keep track of the in-file position of the physical text
+// that in-memory data structures were derived from, and a way to use this
+// positional information to create informative and easy to read errors.
+package errors

errors/errors.go

@@ -37,6 +37,18 @@ func Errorf (position Position, format string, variables ...any) Error {
 // Format returns a formatted string representing an error. This string may take
 // up multiple lines and contain ANSI escape codes. If err does not fulfill the
 // Error interface, err.Error() is returned instead.
+//
+// When the error fulfills the Error interface, the formatted output will
+// be of the general form:
+//   FILE:ROW+1:START+1: MESSAGE
+//   ROW+1 | LINE
+//           ^^^^
+// Where the position of the underline (^^^^) corresponds to the start and end
+// fields in the error's position. Note that the row and column numbers as
+// displayed are increased by one from their normal zero-indexed state, because
+// most editors display row and column numbers starting at 1:1. Additionally,
+// because normal error messages do not produce trailing line breaks, neither
+// does this function.
 func Format (err error) string {
 	if err, ok := err.(Error); ok {
 		return fmt.Sprintf (

errors/position.go

@@ -7,14 +7,19 @@ import "strings"
 // positions in the same file should be created using the same File string, and
 // positions on the same line should be created using the same Line string.
 type Position struct {
-	File   string
-	Line   string
+	File   string // The name of the file
+	Line   string // the text of the line the position is on 
 	
-	Row    int
-	Start  int
-	End    int
+	Row    int // Line number, starting at 0
+	Start  int // Starting column number, starting at 0
+	End    int // Terminating column number, starting at 0
 }
 
+// String returns a string representation of the position of the form:
+//   FILE:ROW+1:START+1
+// Note that the row and column numbers as displayed are increased by one from
+// their normal zero-indexed state, because most editors display row and column
+// numbers starting at 1:1.
 func (pos Position) String () string {
 	return fmt.Sprintf("%s:%d:%d", pos.File, pos.Row + 1, pos.Start + 1)
 }