diff --git a/ir.go b/ir.go
index b311e0f9..312e305c 100644
--- a/ir.go
+++ b/ir.go
@@ -9,6 +9,9 @@ import (
 	"golang.org/x/tools/go/ssa"
 )
 
+// This file provides a wrapper around go/ssa values and adds extra
+// functionality to them.
+
 // View on all functions, types, and globals in a program, with analysis
 // results.
 type Program struct {
diff --git a/passes.go b/passes.go
index 7ca4aaeb..c57267c7 100644
--- a/passes.go
+++ b/passes.go
@@ -5,6 +5,10 @@ import (
 	"golang.org/x/tools/go/ssa"
 )
 
+// This function implements several optimization passes (analysis + transform)
+// to optimize code in SSA form before it is compiled to LLVM IR. It is based on
+// the IR defined in ir.go.
+
 // Make a readable version of the method signature (including the function name,
 // excluding the receiver name). This string is used internally to match
 // interfaces and to call the correct method on an interface. Examples: