feat: meaningful comments for internal packages

internal/cli/exit.go

@@ -1,3 +1,4 @@
+// Package "cli" provides miscellaneous helper functions.
 package cli
 
 import (

internal/config/config.go

@@ -1,3 +1,4 @@
+// Package "config" parses ad handles the user settings given to the program.
 package config
 
 // Configuration settings for the program.

internal/engine/engine.go

@@ -1,3 +1,5 @@
+// Package "engine" provides an extensible interface for users to interfact with
+// lambda calculus.
 package engine
 
 import (
@@ -6,16 +8,19 @@ import (
 	"git.maximhutz.com/max/lambda/pkg/lambda"
 )
 
+// A process for reducing one lambda expression.
 type Engine struct {
 	Config     *config.Config
 	Expression *lambda.Expression
 	emitter.Emitter
 }
 
+// Create a new engine, given an unreduced lambda expression.
 func New(config *config.Config, expression *lambda.Expression) *Engine {
 	return &Engine{Config: config, Expression: expression}
 }
 
+// Begin the reduction process.
 func (e Engine) Run() {
 	e.Emit("start")
 

internal/explanation/tracker.go

@@ -1,3 +1,5 @@
+// Package "explanation" provides a observer to gather the reasoning during the
+// reduction, and present a thorough explanation to the user for each step.
 package explanation
 
 import (
@@ -7,10 +9,12 @@ import (
 	"git.maximhutz.com/max/lambda/pkg/lambda"
 )
 
+// Track the reductions made by a reduction proess.
 type Tracker struct {
 	process *engine.Engine
 }
 
+// Attaches a new explanation tracker to a process.
 func Track(process *engine.Engine) *Tracker {
 	tracker := &Tracker{process: process}
 	process.On("start", tracker.Start)

internal/performance/tracker.go

@@ -1,3 +1,5 @@
+// Package "performance" provides a tracker to observer CPU performance during
+// execution.
 package performance
 
 import (
@@ -6,16 +8,20 @@ import (
 	"runtime/pprof"
 )
 
+// Observes a reduction process, and publishes a CPU performance profile on
+// completion.
 type Tracker struct {
 	File        string
 	filePointer *os.File
 	Error       error
 }
 
+// Create a performance tracker that outputs a profile to "file".
 func Track(file string) *Tracker {
 	return &Tracker{File: file}
 }
 
+// Begin profiling.
 func (t *Tracker) Start() {
 	var absPath string
 
@@ -40,6 +46,7 @@ func (t *Tracker) Start() {
 	}
 }
 
+// Stop profiling.
 func (t *Tracker) End() {
 	pprof.StopCPUProfile()
 	t.filePointer.Close()

internal/statistics/statistics.go

@@ -1,3 +1,5 @@
+// Package "statistics" provides a way to observer reduction speed during
+// execution.
 package statistics
 
 import (
@@ -5,15 +7,18 @@ import (
 	"strings"
 )
 
+// Statistics for a specific reduction.
 type Results struct {
 	StepsTaken  uint64 // Number of steps taken during execution.
 	TimeElapsed uint64 // The time (ms) taken for execution to complete.
 }
 
+// Returns the average number of operations per second of the execution.
 func (r Results) OpsPerSecond() float32 {
 	return float32(r.StepsTaken) / (float32(r.TimeElapsed) / 1000)
 }
 
+// Format the results as a string.
 func (r Results) String() string {
 	builder := strings.Builder{}
 	fmt.Fprintln(&builder, "Time Spent:", r.TimeElapsed, "ms")

internal/statistics/tracker.go

@@ -6,11 +6,13 @@ import (
 	"time"
 )
 
+// An observer, to track reduction performance.
 type Tracker struct {
 	start time.Time
 	steps uint64
 }
 
+// Create a new reduction performance tracker.
 func Track() *Tracker {
 	return &Tracker{}
 }