4 files changed, 28 insertions, 0 deletions
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 {