6 files changed, 44 insertions, 1 deletions
diff --git a/internal/event/pair.go b/internal/event/pair.go
index 4b93013..28b553d 100644
--- a/internal/event/pair.go
+++ b/internal/event/pair.go
@@ -8,7 +8,16 @@ import (
 	"strings"
 )
 
-// Represents a pair of enter and exit events (e.g. entering the syscall + exiting it)
+// Pair represents a matched syscall enter/exit pair together with derived metadata.
+//
+// Timing semantics for Duration (durationNs) and DurationToPrev (durationToPrevNs),
+// mirroring the README:
+//   - Duration is the syscall runtime on the same thread: exit(current) - enter(current).
+//   - DurationToPrev is the inter-syscall gap on the same thread: enter(current) - exit(previous).
+//   - DurationToPrev is tracked per TID; the first observed Pair for a TID has DurationToPrev == 0.
+//   - The inter-syscall gap is attributed to the current Pair (the one whose enter closes the gap).
+//   - There is no separate "idle" pseudo-event bucket; aggregated views should use DurationToPrev
+//     when they want to emphasize inter-syscall time.
 type Pair struct {
 	EnterEv, ExitEv Event
 	File            file.File
diff --git a/internal/flamegraph/counter.go b/internal/flamegraph/counter.go
index c12453a..ae727d4 100644
--- a/internal/flamegraph/counter.go
+++ b/internal/flamegraph/counter.go
@@ -4,6 +4,13 @@ import (
 	"fmt"
 )
 
+// Counter aggregates statistics for a logical flamegraph node.
+//
+// Duration and DurationToPrev use the same timing semantics as event.Pair:
+//   - Duration is the syscall runtime on the same thread.
+//   - DurationToPrev is the inter-syscall gap on the same thread and is attributed
+//     to the current node; there is no separate "idle" pseudo-node.
+// Bytes is only populated for read/write/transfer syscalls.
 type Counter struct {
 	Count          uint64
 	Duration       uint64
diff --git a/internal/flamegraph/nativesvg.go b/internal/flamegraph/nativesvg.go
index 831ffed..89a3e6b 100644
--- a/internal/flamegraph/nativesvg.go
+++ b/internal/flamegraph/nativesvg.go
@@ -8,6 +8,12 @@ import (
 	"strings"
 )
 
+// NativeSVG generates interactive flamegraph SVGs directly from .ior.zst data files.
+//
+// Flamegraphs are generated natively by ior from .ior.zst data files; no external
+// flamegraph tool is required. The CLI typically drives this via the -ior flag,
+// which reads trace data, aggregates it into a trie of stack frames (e.g. pid,path,tracepoint)
+// and renders a self-contained SVG that can be viewed in a browser.
 type NativeSVG struct {
 	fields     []string
 	countField string
diff --git a/internal/flamegraph/svgwriter.go b/internal/flamegraph/svgwriter.go
index a2bc3ed..9cdb441 100644
--- a/internal/flamegraph/svgwriter.go
+++ b/internal/flamegraph/svgwriter.go
@@ -24,6 +24,11 @@ var fnv32aPool = sync.Pool{
 	},
 }
 
+// SVGConfig controls the layout and styling of generated flamegraph SVGs.
+//
+// Width is the virtual canvas width in pixels, FrameHeight is the height of each
+// stack frame row, FontSize is the base font size, and MinWidthPx controls the
+// minimum rendered width for a frame (smaller frames are skipped to avoid noise).
 type SVGConfig struct {
 	Title       string
 	Width       int
@@ -42,6 +47,11 @@ func defaultSVGConfig() SVGConfig {
 	}
 }
 
+// WriteSVG renders a flamegraph trie into an interactive SVG document.
+//
+// The output is a self-contained SVG that includes embedded CSS and JavaScript
+// for zoom, search, and highlighting, and is designed to be served directly to
+// a browser (for example via ServeSVG) without any external assets.
 func WriteSVG(w io.Writer, t *trie, cfg SVGConfig) error {
 	if cfg.Width <= 0 || cfg.FrameHeight <= 0 || cfg.FontSize <= 0 || cfg.MinWidthPx <= 0 {
 		cfg = defaultSVGConfig()
diff --git a/internal/flamegraph/webserver.go b/internal/flamegraph/webserver.go
index 7925011..b1a68e9 100644
--- a/internal/flamegraph/webserver.go
+++ b/internal/flamegraph/webserver.go
@@ -13,6 +13,11 @@ import (
 	"time"
 )
 
+// ServeSVG starts a small HTTP server that serves a single flamegraph SVG.
+//
+// It prints a URL of the form http://HOSTNAME:PORT/abs/path/to.svg and blocks until
+// the user presses Ctrl+C or the process receives SIGTERM, at which point the server
+// is shut down gracefully.
 func ServeSVG(svgFile string) error {
 	absPath, err := filepath.Abs(svgFile)
 	if err != nil {
diff --git a/internal/ior.go b/internal/ior.go
index b136931..55c637c 100644
--- a/internal/ior.go
+++ b/internal/ior.go
@@ -91,6 +91,12 @@ func attachTracepointsWith(module tracepointModule, shouldAttach func(string) bo
 	return nil
 }
 
+// Run is the main entry point for the ior binary.
+//
+// When -ior=<trace.ior.zst> is provided it reads the compressed trace data, generates
+// a native flamegraph SVG (using the selected fields and count metric) and then serves
+// it via an embedded HTTP server. Without -ior, Run either executes trace mode or
+// starts the TUI, depending on the active flags.
 func Run() error {
 	flags.PrintVersion()
 	cfg := flags.Get()