Document ResultIterator behaviour.

filter.go

@@ -13,17 +13,19 @@ type FilterIterator struct {
 	iter ResultIterator
 }
 
-func NewFilterIterator(wrap ResultIterator, filter FilterFunc) *FilterIterator {
+// NewFilterIterator wraps a ResultIterator. The filter function is applied
+// to each value returned by a call to iter.Next.
+func NewFilterIterator(iter ResultIterator, filter FilterFunc) *FilterIterator {
 	return &FilterIterator{
 		filter: filter,
-		iter:   wrap,
+		iter:   iter,
 	}
 }
 
 // WatchCh returns the watch channel of the wrapped iterator.
 func (f *FilterIterator) WatchCh() <-chan struct{} { return f.iter.WatchCh() }
 
-// Next returns the next non-filtered result from the wrapped iterator
+// Next returns the next non-filtered result from the wrapped iterator.
 func (f *FilterIterator) Next() interface{} {
 	for {
 		if value := f.iter.Next(); value == nil || !f.filter(value) {

txn.go

@@ -52,9 +52,9 @@ func (txn *Txn) TrackChanges() {
 	}
 }
 
-// readableIndex returns a transaction usable for reading the given
-// index in a table. If a write transaction is in progress, we may need
-// to use an existing modified txn.
+// readableIndex returns a transaction usable for reading the given index in a
+// table. If transaction is a write transaction with modifications a clone of the
+// modified index will be returned.
 func (txn *Txn) readableIndex(table, index string) *iradix.Txn {
 	// Look for existing transaction
 	if txn.write && txn.modified != nil {
@@ -663,15 +663,23 @@ func (txn *Txn) getIndexValue(table, index string, args ...interface{}) (*IndexS
 	return indexSchema, val, err
 }
 
-// ResultIterator is used to iterate over a list of results
-// from a Get query on a table.
+// ResultIterator is used to iterate over a list of results from a query on a table.
+//
+// When a ResultIterator is created from a write transaction, the results from
+// Next will reflect a snapshot of the table at the time the ResultIterator is
+// created.
+//
+// When a ResultIterator is created from a write transaction, and there are already
+// modifications to the index used by the iterator, the modification cache of the
+// index will be invalidated. This may result in some additional allocations if
+// the same node in the index is modified again.
 type ResultIterator interface {
 	WatchCh() <-chan struct{}
 	Next() interface{}
 }
 
-// Get is used to construct a ResultIterator over all the
-// rows that match the given constraints of an index.
+// Get is used to construct a ResultIterator over all the rows that match the
+// given constraints of an index.
 func (txn *Txn) Get(table, index string, args ...interface{}) (ResultIterator, error) {
 	indexIter, val, err := txn.getIndexIterator(table, index, args...)
 	if err != nil {