docs: iterator

pkg/iterator/iterator.go

@@ -1,35 +1,37 @@
-/*
+// Package iterator defines a generic way to iterator over a slice of data.
-Package "iterator"
-*/
 package iterator
 
 import "fmt"
 
-// An iterator over slices.
+// An Iterator traverses over slices.
 type Iterator[T any] struct {
 	items []T
 	index int
 }
 
-// Create a new iterator, over a set of items.
+// Of creates a new iterator, over a set of defined items.
 func Of[T any](items []T) *Iterator[T] {
 	return &Iterator[T]{items: items, index: 0}
 }
 
-// Returns the current position of the iterator.
+// Index returns the current position of the iterator.
 func (i Iterator[T]) Index() int {
 	return i.index
 }
 
+// Copy returns a identical clone of the iterator. The underlying data structure
+// is not cloned.
 func (i Iterator[T]) Copy() *Iterator[T] {
 	return &Iterator[T]{items: i.items, index: i.index}
 }
 
+// Sync returns the iterator to the position of another. It is assumed that the
+// iterators both operate on the same set of data.
 func (i *Iterator[T]) Sync(o *Iterator[T]) {
 	i.index = o.index
 }
 
-// Create a new iterator, over a set of items.
+// Get returns the datum at the current position of the iterator.
 func (i Iterator[T]) Get() (T, error) {
 	var null T
 	if i.Done() {
@@ -39,6 +41,7 @@ func (i Iterator[T]) Get() (T, error) {
 	return i.items[i.index], nil
 }
 
+// MustGet is a version of Get, that panics if the datum cannot be returned.
 func (i Iterator[T]) MustGet() T {
 	var null T
 	if i.Done() {
@@ -48,13 +51,16 @@ func (i Iterator[T]) MustGet() T {
 	return i.items[i.index]
 }
 
+// Forward increments the iterator if the iterator is not yet at the end of the
+// slice.
 func (i *Iterator[T]) Forward() {
 	if !i.Done() {
 		i.index++
 	}
 }
 
-// Create a new iterator, over a set of items.
+// Next attempts to increment the iterator. Returns an error if it cannot be
+// incremented.
 func (i *Iterator[T]) Next() (T, error) {
 	item, err := i.Get()
 	if err == nil {
@@ -64,16 +70,20 @@ func (i *Iterator[T]) Next() (T, error) {
 	return item, err
 }
 
-// Create a new iterator, over a set of items.
+// Back decrements the iterator. If the iterator is already at the beginning of
+// the slice, this is a no-op.
 func (i *Iterator[T]) Back() {
 	i.index = max(i.index-1, 0)
 }
 
-// Returns the current position of the iterator.
+// Done returns whether the iterator is at the end of the slice or not.
 func (i Iterator[T]) Done() bool {
 	return i.index == len(i.items)
 }
 
+// Do attempts to perform an operation using the iterator. If the operation
+// succeeds, the iterator is updated. If the operation fails, the iterator is
+// rolled back, and an error is returned.
 func Do[T any, U any](i *Iterator[T], fn func(i *Iterator[T]) (U, error)) (U, error) {
 	i2 := i.Copy()