Made documentation a bit better

analyzer/analyzer.go

@@ -1,3 +1,14 @@
+/*
+Package analyzer implements a semantic analyzer for the ARF language. In it,
+there is a function called Analyze which takes in a module path and returns a
+table of sections representative of that module. The result of this operation is
+not cached.
+
+The section table returned by Analyze can be expected to be both syntactically
+correct and semantically sound.
+
+This package automatically invokes the parser and lexer packages.
+*/
 package analyzer
 
 import "os"
@@ -16,8 +27,9 @@ type analysisOperation struct {
 	currentTree     parser.SyntaxTree
 }
 
-// Analyze performs a semantic analyisys on the module specified by path, and
-// returns a SectionTable that can be translated into C.
+// Analyze performs a semantic analysis on the module specified by path, and
+// returns a SectionTable that can be translated into C. The result of this is
+// not cached.
 func Analyze (modulePath string, skim bool) (table SectionTable, err error) {
 	if modulePath[0] != '/' {
 		cwd, _ := os.Getwd()

analyzer/literals.go

@@ -2,31 +2,30 @@ package analyzer
 
 import "fmt"
 
+// IntLiteral represents a constant signed integer value.
 type IntLiteral struct {
 	locatable
 	value int64
 }
 
+// UIntLiteral represents a constant unsigned itneger value.
 type UIntLiteral struct {
 	locatable
 	value uint64
 }
 
+// FloatLiteral represents a constant floating point value.
 type FloatLiteral struct {
 	locatable
 	value float64
 }
 
+// StringLiteral represents a constant text value.
 type StringLiteral struct {
 	locatable
 	value string
 }
 
-type RuneLiteral struct {
-	locatable
-	value rune
-}
-
 // ToString outputs the data in the argument as a string.
 func (literal IntLiteral) ToString (indent int) (output string) {
 	output += doIndent(indent, fmt.Sprint("arg int ", literal.value, "\n"))

analyzer/primitives.go

@@ -2,22 +2,53 @@ package analyzer
 
 // This is a global, cannonical list of primitive and built-in types.
 
-var PrimitiveF32  = createPrimitive("Int",  Type {})
-var PrimitiveF64  = createPrimitive("Int",  Type {})
+// PrimitiveF32 is a 32 bit floating point primitive.
+var PrimitiveF32  = createPrimitive("F32",  Type {})
+
+// PrimitiveF64 is a 64 bit floating point primitive.
+var PrimitiveF64  = createPrimitive("F64",  Type {})
+
+// PrimitiveInt is a signed integer word primitive.
 var PrimitiveInt  = createPrimitive("Int",  Type {})
+
+// PrimitiveUInt is an unsigned integer word primitive.
 var PrimitiveUInt = createPrimitive("UInt", Type {})
+
+// PrimitiveI8 is a signed 8 bit integer primitive.
 var PrimitiveI8   = createPrimitive("I8",   Type {})
+
+// PrimitiveI16 is a signed 16 bit integer primitive.
 var PrimitiveI16  = createPrimitive("I16",  Type {})
+
+// PrimitiveI32 is a signed 32 bit integer primitive.
 var PrimitiveI32  = createPrimitive("I32",  Type {})
+
+// PrimitiveI64 is a signed 64 bit integer primitive.
 var PrimitiveI64  = createPrimitive("I64",  Type {})
+
+// PrimitiveI8 is an unsigned 8 bit integer primitive.
 var PrimitiveU8   = createPrimitive("U8",   Type {})
+
+// PrimitiveI16 is an unsigned 16 bit integer primitive.
 var PrimitiveU16  = createPrimitive("U16",  Type {})
+
+// PrimitiveI32 is an unsigned 32 bit integer primitive.
 var PrimitiveU32  = createPrimitive("U32",  Type {})
+
+// PrimitiveI64 is an unsigned 64 bit integer primitive.
 var PrimitiveU64  = createPrimitive("U64",  Type {})
+
+// PrimitiveObj is a blank object primitive.
 var PrimitiveObj  = createPrimitive("Obj",  Type {})
+
+// PrimitiveFace is a blank interface primitive. It accepts any value.
 var PrimitiveFace = createPrimitive("Face", Type {})
+
+// PrimitiveFunc is a blank function interface primitive. It is useless.
 var PrimitiveFunc = createPrimitive("Func", Type {})
 
+// BuiltInString is a built in string type. It is a dynamic array of UTF-32
+// codepoints.
 var BuiltInString = createPrimitive("String", Type {
 	actual: &PrimitiveU32,
 	kind:   TypeKindVariableArray,

lexer/lexer.go

@@ -1,3 +1,8 @@
+/*
+Package lexer implements a tokenizer for the ARF language. It contains a
+function called Tokenize which takes in a file from the ARF file package, and
+outputs an array of tokens.
+*/
 package lexer
 
 import "io"

parser/parser.go

@@ -1,3 +1,15 @@
+/*
+Package parser implements a parser for the ARF language. It contains an abstract
+syntax tree (SyntaxTree), various tree nodes, and a function called Fetch that
+returns a SyntaxTree for the module located at the given path. Internally, the
+parser caches parsing results so Fetch may be called frequently.
+
+Trees returned by this package can be expected to be internally consistent and
+syntactically corred, but not semantically correct. Ensuring the semantic
+integrity of ARF code is the job of the analyzer package.
+
+This package automatically invokes lexer before parsing module files.
+*/
 package parser
 
 import "io"
@@ -18,9 +30,9 @@ type parsingOperation struct {
 	tree SyntaxTree
 }
 
-// Fetch returns the parsed module located at the specified path, and returns an
-// abstract syntax tree. If the module has not yet been parsed, it parses it
-// first.
+// Fetch returns the parsed module located at the specified path as a
+// SyntaxTree. If the module has not yet been parsed, it parses it first. If it
+// has, it grabs it out of a cache. This function can be called frequently.
 func Fetch (modulePath string, skim bool) (tree SyntaxTree, err error) {
 	if modulePath[0] != '/' {
 		panic("module path did not begin at filesystem root")