feat: add docs

Author: mxmgorin

pkg/chip8/audio.go

@@ -13,12 +13,29 @@ const (
 	AudioXOChip                  // XO-Chip 16-byte pattern
 )
 
+// Audio represents the CHIP-8 / XO-CHIP sound generator state.
+//
+// It models the programmable audio pattern, pitch, and playback
+// position used by the virtual machine. The Audio type contains
+// no host-specific audio output logic and is controlled by the sound timer.
 type Audio struct {
-	pattern [16]byte // 128 bits
-	pitch   byte     // default in xochip is 64 meaning 4000 Hz
-	st      byte
-	phase   float64 // position inside pattern
-	mode    AudioMode
+	// pattern is a 128-bit (16-byte) audio pattern buffer.
+	// Each bit represents one step of the waveform.
+	pattern [16]byte
+
+	// pitch controls the playback frequency of the pattern.
+	// In XO-CHIP, the default value is 64, corresponding to 4000 Hz.
+	pitch byte
+
+	// st is the sound timer. While ST > 0, audio playback is active.
+	st byte
+
+	// phase represents the current playback position within the pattern.
+	// It is expressed as a fractional index to allow sub-step advancement.
+	phase float64
+
+	// mode selects the active audio mode (e.g. CHIP-8 or XO-CHIP).
+	mode AudioMode
 }
 
 func NewAudio() Audio {

pkg/chip8/cpu.go

@@ -6,6 +6,7 @@ import (
 
 const opSize = 2
 
+// CPU represents the CHIP-8 processor state.
 type CPU struct {
 	v      [16]byte
 	i      uint16
@@ -52,7 +53,11 @@ func (c *CPU) fetch(memory *Memory) uint16 {
 	return opcode
 }
 
-func (c *CPU) execute(op uint16, memory *Memory, display *Display, keypad *Keypad, audio *Audio) {
+// Execute executes a single instruction.
+//
+// It fetches the opcode at PC, decodes it, executes it,
+// and updates timers as specified by the specification.
+func (c *CPU) Execute(op uint16, memory *Memory, display *Display, keypad *Keypad, audio *Audio) {
 	switch op & 0xF000 {
 	case 0x0000:
 		switch op & 0x00FF {

pkg/chip8/display.go

@@ -19,7 +19,14 @@ func (s Size) Area() int {
 	return s.Width * s.Height
 }
 
+// Display represents the CHIP-8 / XO-CHIP video state.
+//
+// It maintains one or more bitplanes, the active resolution mode,
+// and internal flags used to coordinate drawing and vertical blanking.
+// The Display type contains no rendering or host-specific output logic.
 type Display struct {
+	// Planes contains the video bitplanes.
+	// CHIP-8 uses a single plane; XO-CHIP supports up to four planes.
 	Planes        [4][]byte
 	size          Size
 	dirty         bool

pkg/chip8/doc.go

@@ -0,0 +1,6 @@
+// Package chip8 implements a pure CHIP-8 virtual machine.
+//
+// It implements all core components of the system, including the CPU,
+// memory, timers, display, sound, and input state. The package is fully
+// platform-agnostic and contains no host- or UI-specific code.
+package chip8

pkg/chip8/memory.go

@@ -47,6 +47,7 @@ var fontSets = [240]byte{
 	0xFE, 0x66, 0x62, 0x64, 0x7C, 0x64, 0x60, 0x60, 0xF0, 0x00, // F
 }
 
+// Memory represents the CHIP-8 address space.
 type Memory struct {
 	bytes [MemorySize]byte
 }

pkg/chip8/vm.go

@@ -5,11 +5,22 @@ import (
 	"time"
 )
 
+const (
+	// Timer decrements at 60 Hz independent of CPU frequency.
+	TimerHz = 60
+)
+
 type FrameState struct {
 	Dirty bool
 	Beep  bool
 }
 
+// VM represents a complete CHIP-8 virtual machine instance.
+//
+// It aggregates all core subsystems required for execution, including
+// CPU, memory, display, input, and audio. A VM instance owns its internal
+// timing state and is responsible for coordinating CPU execution and
+// timer updates.
 type VM struct {
 	CPU        CPU
 	Memory     Memory
@@ -18,7 +29,6 @@ type VM struct {
 	Audio      Audio
 	romSize    int
 	cpuHz      float64
-	timerHz    float64
 	cycleAccum float64
 	timerAccum float64
 }
@@ -30,7 +40,6 @@ func NewVM() *VM {
 		Display: NewDisplay(),
 		Keypad:  NewKeypad(),
 		Audio:   NewAudio(),
-		timerHz: 60.0,
 		cpuHz:   DefaultConf.CPUHz(),
 	}
 }
@@ -68,7 +77,7 @@ func (vm *VM) Reset() {
 func (vm *VM) Step() {
 	if !vm.Display.pendingVBlank || !vm.CPU.Quirks.WaitVBlank {
 		opcode := vm.CPU.fetch(&vm.Memory)
-		vm.CPU.execute(opcode, &vm.Memory, &vm.Display, &vm.Keypad, &vm.Audio)
+		vm.CPU.Execute(opcode, &vm.Memory, &vm.Display, &vm.Keypad, &vm.Audio)
 	}
 }
 
@@ -82,7 +91,7 @@ func (vm *VM) RunFrame(frameDelta time.Duration) FrameState {
 		vm.Step()
 	}
 
-	vm.timerAccum += vm.timerHz * dt
+	vm.timerAccum += TimerHz * dt
 
 	for vm.timerAccum >= 1 {
 		vm.timerAccum -= 1

pkg/db/doc.go

@@ -0,0 +1,4 @@
+// Package db stores metadata about programs, ROMs and platforms.
+//
+// The package contains no emulator or application logic and is limited to data definitions and querying.
+package db

pkg/host/doc.go

@@ -0,0 +1,7 @@
+// Package host provides reusable, platform-facing infrastructure
+// shared across host applications.
+//
+// It contains code that integrates the CHIP-8 virtual machine with
+// concrete runtime environments (CLI, desktop, mobile, or web) and
+// may depend on pkg/chip8 and pkg/db.
+package host

pkg/host/emu.go

@@ -10,6 +10,12 @@ import (
 	"github.com/mxmgorin/ch8go/pkg/db"
 )
 
+// Emu represents a host-level emulator instance.
+//
+// It binds a CHIP-8 virtual machine to host-provided services such as
+// metadata lookup, palette configuration, and framebuffer management.
+// Emu owns execution control state (pause, timing) but does not contain
+// core emulation logic.
 type Emu struct {
 	VM            *chip8.VM
 	MetaDB        *db.MetaDB