diff --git a/interfaces/interfaces.go b/interfaces/interfaces.go
index f0b5cf6..606b983 100644
--- a/interfaces/interfaces.go
+++ b/interfaces/interfaces.go
@@ -1,10 +1,19 @@
 package interfaces
 
+/*
+Interface for values that can be compared.
+*/
 type Comparer interface {
+	// Should return `true` when values are equal; `false` when not equal.
 	Equal(other Comparer) bool
+	// Should return `true` when the comparer is less than `other`; `false` when not less than.
 	Lt(other Comparer) bool
 }
 
+/*
+Interface for values that can be iterated over.
+*/
 type Iterator interface {
-	Iter() chan interface{}
+	// Return a read-only channel of the iterator values.
+	Iter() <-chan interface{}
 }
diff --git a/internal/ffi/native/linux/libpolar.a b/internal/ffi/native/linux/libpolar.a
index 22a5238..cc64d17 100644
Binary files a/internal/ffi/native/linux/libpolar.a and b/internal/ffi/native/linux/libpolar.a differ
diff --git a/internal/ffi/native/macos/libpolar.a b/internal/ffi/native/macos/libpolar.a
index 1db7068..c9ae451 100644
Binary files a/internal/ffi/native/macos/libpolar.a and b/internal/ffi/native/macos/libpolar.a differ
diff --git a/oso.go b/oso.go
index a880347..b044434 100644
--- a/oso.go
+++ b/oso.go
@@ -4,12 +4,20 @@ import (
 	"reflect"
 )
 
+/*
+The central object to manage policy state and verify requests.
+*/
 type Oso struct {
 	p *Polar
 }
 
 /*
 Construct a new Oso instance.
+
+	import oso "github.com/osohq/go-oso"
+	if o, err := oso.NewOso(); err != nil {
+		t.Fatalf("Failed to set up Oso: %v", err)
+	}
 */
 func NewOso() (Oso, error) {
 	if p, e := newPolar(); e != nil {
@@ -19,26 +27,45 @@ func NewOso() (Oso, error) {
 	}
 }
 
+/*
+Load Polar policy from a ".polar" file, checking that all inline queries succeed.
+*/
 func (o Oso) LoadFile(f string) error {
 	return (*o.p).loadFile(f)
 }
 
+/*
+Load Polar policy from a string, checking that all inline queries succeed.
+*/
 func (o Oso) LoadString(s string) error {
 	return (*o.p).loadString(s)
 }
 
+/*
+Clear all rules from the Oso knowledge base (i.e., remove all loaded policies).
+*/
 func (o Oso) ClearRules() error {
 	return (*o.p).clearRules()
 }
 
+/*
+Register a Go type so that it can be referenced within Polar files.
+*/
 func (o Oso) RegisterClass(cls reflect.Type) error {
 	return (*o.p).registerClass(cls, nil)
 }
 
+/*
+Register a Go type under a certain name/alias, so that it can be referenced
+within Polar files by that name.
+*/
 func (o Oso) RegisterClassWithName(cls reflect.Type, name string) error {
 	return (*o.p).registerClass(cls, &name)
 }
 
+/*
+Register a Go value as a Polar constant variable called `name`.
+*/
 func (o Oso) RegisterConstant(value interface{}, name string) error {
 	return (*o.p).registerConstant(value, name)
 }
diff --git a/query.go b/query.go
index d22c6eb..916990b 100644
--- a/query.go
+++ b/query.go
@@ -13,10 +13,13 @@ import (
 	. "github.com/osohq/go-oso/types"
 )
 
+/*
+Execute a Polar query through the FFI/event interface.
+*/
 type Query struct {
 	ffiQuery ffi.QueryFfi
 	host     host.Host
-	calls    map[uint64]chan interface{}
+	calls    map[uint64]<-chan interface{}
 }
 
 // NATIVE_TYPES = [int, float, bool, str, dict, type(None), list]
@@ -25,7 +28,7 @@ func newQuery(ffiQuery ffi.QueryFfi, host host.Host) Query {
 	return Query{
 		ffiQuery: ffiQuery,
 		host:     host,
-		calls:    make(map[uint64]chan interface{}),
+		calls:    make(map[uint64]<-chan interface{}),
 	}
 }
 
@@ -49,6 +52,10 @@ func (q *Query) resultsChannel() (<-chan map[string]interface{}, <-chan error) {
 	return results, errors
 }
 
+/*
+Executes the query until all results have been returned, and returns results
+as a list of binding maps.
+*/
 func (q *Query) GetAllResults() ([]map[string]interface{}, error) {
 	results := make([]map[string]interface{}, 0)
 	for {
@@ -63,6 +70,10 @@ func (q *Query) GetAllResults() ([]map[string]interface{}, error) {
 	return results, nil
 }
 
+/*
+Get the next query result. Returns a pointer to a map of result bindings,
+or a nil pointer if there are no results.
+*/
 func (q *Query) Next() (*map[string]interface{}, error) {
 	if q == nil {
 		return nil, fmt.Errorf("query has already finished")
diff --git a/tests/parity_test.go b/tests/parity_test.go
index 1b29061..45f4777 100644
--- a/tests/parity_test.go
+++ b/tests/parity_test.go
@@ -45,7 +45,7 @@ func (ic IterableClass) Sum() int {
 	return res
 }
 
-func (ic IterableClass) Iter() chan interface{} {
+func (ic IterableClass) Iter() <-chan interface{} {
 	c := make(chan interface{})
 	go func() {
 		for _, v := range ic.Elems {
diff --git a/types/polar_types.go b/types/polar_types.go
index ceb57ac..ce385ea 100644
--- a/types/polar_types.go
+++ b/types/polar_types.go
@@ -1,5 +1,7 @@
 package types
 
+// Code generated. DO NOT EDIT.
+
 import (
 	"encoding/json"
 	"errors"