Improve documentation for iter package

Author: BooleanCat

iter/chain.go

@@ -8,7 +8,7 @@ type ChainIter[T any] struct {
 	iteratorIndex int
 }
 
-// Chain instantiates a [ChainIter] that will yield all items in the provided
+// Chain instantiates a [*ChainIter] that will yield all items in the provided
 // iterators to exhaustion first to last.
 func Chain[T any](iterators ...Iterator[T]) *ChainIter[T] {
 	return &ChainIter[T]{iterators, 0}

iter/channel.go

@@ -7,8 +7,8 @@ type ChannelIter[T any] struct {
 	item chan T
 }
 
-// FromChannel instantiates a [ChannelIter] that will yield each value from the
-// provided channel.
+// FromChannel instantiates a [*ChannelIter] that will yield each value from
+// the provided channel.
 func FromChannel[T any](ch chan T) *ChannelIter[T] {
 	return &ChannelIter[T]{ch}
 }

iter/counter.go

@@ -2,32 +2,34 @@ package iter
 
 import "github.com/BooleanCat/go-functional/option"
 
-// CountIter implements `Count`. See `Count`'s documentation.
+// CountIter iterator, see [Count].
 type CountIter struct {
 	index int
 }
 
-// Count instantiates a `CountIter` that will iterate over 0 and the
+// Count instantiates a [*CountIter] that will iterate over 0 and the
 // natural numbers. Count is functionally "unlimited" although it does not
 // protect against the integer limit.
 func Count() *CountIter {
 	return new(CountIter)
 }
 
-// Next implements the Iterator interface for `CountIter`.
+// Next implements the [Iterator] interface.
 func (c *CountIter) Next() option.Option[int] {
 	c.index++
 	return option.Some(c.index - 1)
 }
 
 var _ Iterator[int] = new(CountIter)
 
-// Drop is an alternative way of invoking Drop(iter)
+// Drop is a convenience method for [Drop], providing this iterator as an
+// argument.
 func (c *CountIter) Drop(n uint) *DropIter[int] {
 	return Drop[int](c, n)
 }
 
-// Take is an alternative way of invoking Take(iter)
+// Take is a convenience method for [Take], providing this iterator as an
+// argument.
 func (iter *CountIter) Take(n uint) *TakeIter[int] {
 	return Take[int](iter, n)
 }

iter/cycle.go

@@ -2,18 +2,18 @@ package iter
 
 import "github.com/BooleanCat/go-functional/option"
 
-// CycleIter implements `Cycle`. See `Cycle`'s documentation.
+// CycleIter iterator, see [Cycle].
 type CycleIter[T any] struct {
 	iter  Iterator[T]
 	items []T
 	index int
 }
 
-// Cycle instantiates a `CycleIter` yielding all items from the provided
+// Cycle instantiates a [*CycleIter] yielding all items from the provided
 // iterator until exhaustion, and then yields them all over again on repeat.
 //
-// Note that CycleIter stores the members from the underlying iterator so will
-// grow in size as items are yielded until the underlying iterator is
+// Note that [CycleIter] stores the members from the underlying iterator so
+// will grow in size as items are yielded until the underlying iterator is
 // exhausted.
 //
 // In most cases this iterator is infinite, except when the underlying iterator
@@ -23,7 +23,7 @@ func Cycle[T any](iter Iterator[T]) *CycleIter[T] {
 	return &CycleIter[T]{iter, make([]T, 0), 0}
 }
 
-// Next implements the Iterator interface for `CycleIter`.
+// Next implements the [Iterator] interface.
 func (iter *CycleIter[T]) Next() option.Option[T] {
 	if iter.iter != nil {
 		if value, ok := iter.iter.Next().Value(); ok {
@@ -49,12 +49,14 @@ func (iter *CycleIter[T]) Next() option.Option[T] {
 
 var _ Iterator[struct{}] = new(CycleIter[struct{}])
 
-// Drop is an alternative way of invoking Drop(iter)
+// Drop is a convenience method for [Drop], providing this iterator as an
+// argument.
 func (iter *CycleIter[T]) Drop(n uint) *DropIter[T] {
 	return Drop[T](iter, n)
 }
 
-// Take is an alternative way of invoking Take(iter)
+// Take is a convenience method for [Take], providing this iterator as an
+// argument.
 func (iter *CycleIter[T]) Take(n uint) *TakeIter[T] {
 	return Take[T](iter, n)
 }

iter/drop.go

@@ -2,21 +2,21 @@ package iter
 
 import "github.com/BooleanCat/go-functional/option"
 
-// DropIter implements `Drop`. See `Drop`'s documentation.
+// DropIter iterator, see [Drop].
 type DropIter[T any] struct {
 	iter      Iterator[T]
 	count     uint
 	dropped   bool
 	exhausted bool
 }
 
-// Drop instantiates a `DropIter` that will skip the number of items of its
+// Drop instantiates a [*DropIter] that will skip the number of items of its
 // wrapped iterator by the provided count.
 func Drop[T any](iter Iterator[T], count uint) *DropIter[T] {
 	return &DropIter[T]{iter, count, false, false}
 }
 
-// Next implements the Iterator interface for `DropIter`.
+// Next implements the [Iterator] interface.
 func (iter *DropIter[T]) Next() option.Option[T] {
 	if iter.exhausted {
 		return option.None[T]()
@@ -46,17 +46,20 @@ func (iter *DropIter[T]) delegateNext() option.Option[T] {
 
 var _ Iterator[struct{}] = new(DropIter[struct{}])
 
-// Collect is an alternative way of invoking Collect(iter)
+// Collect is a convenience method for [Collect], providing this iterator as
+// an argument.
 func (iter *DropIter[T]) Collect() []T {
 	return Collect[T](iter)
 }
 
-// Drop is an alternative way of invoking Drop(iter)
+// Drop is a convenience method for [Drop], providing this iterator as an
+// argument.
 func (iter *DropIter[T]) Drop(n uint) *DropIter[T] {
 	return Drop[T](iter, n)
 }
 
-// Take is an alternative way of invoking Take(iter)
+// Take is a convenience method for [Take], providing this iterator as an
+// argument.
 func (iter *DropIter[T]) Take(n uint) *TakeIter[T] {
 	return Take[T](iter, n)
 }

iter/exhausted.go

@@ -2,33 +2,36 @@ package iter
 
 import "github.com/BooleanCat/go-functional/option"
 
-// ExhaustedIter implements `Exhausted`. See `Exhausted`'s documentation.
+// ExhaustedIter iterator, see [Exhausted].
 type ExhaustedIter[T any] struct{}
 
-// Exhausted instantiates an `ExhaustedIter` that will immediately be exhausted
-// (`Next` will always return a `None` variant).
+// Exhausted instantiates an [*ExhaustedIter] that will immediately be
+// exhausted (Next will always return a None variant).
 func Exhausted[T any]() *ExhaustedIter[T] {
 	return new(ExhaustedIter[T])
 }
 
-// Next implements the Iterator interface for `ExhaustedIter`.
+// Next implements the [Iterator] interface.
 func (iter *ExhaustedIter[T]) Next() option.Option[T] {
 	return option.None[T]()
 }
 
 var _ Iterator[struct{}] = new(ExhaustedIter[struct{}])
 
-// Collect is an alternative way of invoking Collect(iter)
+// Collect is a convenience method for [Collect], providing this iterator as
+// an argument.
 func (iter *ExhaustedIter[T]) Collect() []T {
 	return Collect[T](iter)
 }
 
-// Drop is an alternative way of invoking Drop(iter)
+// Drop is a convenience method for [Drop], providing this iterator as an
+// argument.
 func (iter *ExhaustedIter[T]) Drop(n uint) *DropIter[T] {
 	return Drop[T](iter, n)
 }
 
-// Take is an alternative way of invoking Take(iter)
+// Take is a convenience method for [Take], providing this iterator as an
+// argument.
 func (iter *ExhaustedIter[T]) Take(n uint) *TakeIter[T] {
 	return Take[T](iter, n)
 }

iter/filter.go

@@ -2,20 +2,20 @@ package iter
 
 import "github.com/BooleanCat/go-functional/option"
 
-// FilterIter implements `Filter`. See `Filter`'s documentation.
+// FilterIter iterator, see [Filter].
 type FilterIter[T any] struct {
 	iter      Iterator[T]
 	fun       func(T) bool
 	exhausted bool
 }
 
-// Filter instantiates a `FilterIter` that selectively yields only results that
-// cause the provided function to return `true`.
+// Filter instantiates a [*FilterIter] that selectively yields only results
+// that cause the provided function to return `true`.
 func Filter[T any](iter Iterator[T], fun func(T) bool) *FilterIter[T] {
 	return &FilterIter[T]{iter, fun, false}
 }
 
-// Next implements the Iterator interface for `Filter`.
+// Next implements the [Iterator] interface.
 func (iter *FilterIter[T]) Next() option.Option[T] {
 	if iter.exhausted {
 		return option.None[T]()
@@ -36,36 +36,39 @@ func (iter *FilterIter[T]) Next() option.Option[T] {
 
 var _ Iterator[struct{}] = new(FilterIter[struct{}])
 
-// Collect is an alternative way of invoking Collect(iter)
+// Collect is a convenience method for [Collect], providing this iterator as
+// an argument.
 func (iter *FilterIter[T]) Collect() []T {
 	return Collect[T](iter)
 }
 
-// Drop is an alternative way of invoking Drop(iter)
+// Drop is a convenience method for [Drop], providing this iterator as an
+// argument.
 func (iter *FilterIter[T]) Drop(n uint) *DropIter[T] {
 	return Drop[T](iter, n)
 }
 
-// Take is an alternative way of invoking Take(iter)
+// Take is a convenience method for [Take], providing this iterator as an
+// argument.
 func (iter *FilterIter[T]) Take(n uint) *TakeIter[T] {
 	return Take[T](iter, n)
 }
 
-// Exclude instantiates a `FilterIter` that selectively yields only results that
-// cause the provided function to return `false`.
+// Exclude instantiates a [*FilterIter] that selectively yields only results
+// that cause the provided function to return `false`.
 func Exclude[T any](iter Iterator[T], fun func(T) bool) *FilterIter[T] {
 	inverse := func(t T) bool { return !fun(t) }
 	return &FilterIter[T]{iter, inverse, false}
 }
 
-// FilterMapIter implements `FilterMap`. See `FilterMap`'s documentation.
+// FilterMapIter iterator, see [FilterMap].
 type FilterMapIter[T any, U any] struct {
 	iter      Iterator[T]
 	fn        func(T) option.Option[U]
 	exhausted bool
 }
 
-// Next implements the Iterator interface for `FilterMapIter`.
+// Next implements the [Iterator] interface.
 func (iter *FilterMapIter[T, U]) Next() option.Option[U] {
 	if iter.exhausted {
 		return option.None[U]()
@@ -87,24 +90,27 @@ func (iter *FilterMapIter[T, U]) Next() option.Option[U] {
 
 var _ Iterator[struct{}] = new(FilterMapIter[struct{}, struct{}])
 
-// Accepts an underlying iterator as data source and a filtering + mapping function
-// it allows the user to filter elements by returning a None variant and to transform
-// elements by returning a Some variant.
+// FilterMap instantiates a [*FilterMapIter] that selectively yields only
+// results that cause the provided function to return `true` with a map
+// operation performed on them.
 func FilterMap[T any, U any](itr Iterator[T], fun func(T) option.Option[U]) *FilterMapIter[T, U] {
 	return &FilterMapIter[T, U]{itr, fun, false}
 }
 
-// Collect is an alternative way of invoking Collect(iter)
+// Collect is a convenience method for [Collect], providing this iterator as
+// an argument.
 func (iter *FilterMapIter[T, U]) Collect() []U {
 	return Collect[U](iter)
 }
 
-// Drop is an alternative way of invoking Drop(iter)
+// Drop is a convenience method for [Drop], providing this iterator as an
+// argument.
 func (iter *FilterMapIter[T, U]) Drop(n uint) *DropIter[U] {
 	return Drop[U](iter, n)
 }
 
-// Take is an alternative way of invoking Take(iter)
+// Take is a convenience method for [Take], providing this iterator as an
+// argument.
 func (iter *FilterMapIter[T, U]) Take(n uint) *TakeIter[U] {
 	return Take[U](iter, n)
 }

iter/iter.go

@@ -4,16 +4,16 @@ import "github.com/BooleanCat/go-functional/option"
 
 // Iterator declares that each Iterator must implement a Next method.
 // Successive calls to the next method shall return the next item in the
-// Iterator, wrapped in an `Option.Some` variant.
+// Iterator, wrapped in an [option.Some] variant.
 //
-// Exhausted Iterators shall return a `None` variant of `Option` on every
-// subsequent call.
+// Exhausted Iterators shall return a [option.None] variant on every subsequent
+// call.
 type Iterator[T any] interface {
 	Next() option.Option[T]
 }
 
-// Collect consumes an Iterator and returns all remaining items within a slice.
-// It does not protect against infinite Iterators.
+// Collect consumes an [Iterator] and returns all remaining items within a
+// slice. It does not protect against infinite Iterators.
 func Collect[T any](iter Iterator[T]) []T {
 	items := make([]T, 0)
 
@@ -26,10 +26,10 @@ func Collect[T any](iter Iterator[T]) []T {
 	}
 }
 
-// Fold consumes an Iterator and returns the final result of applying the accumulator function to each element.
-// The accumulator function accepts two arguments - an accumulator and an element and returns a new  accumulator.
-// The initial value is the accumulator for the first call.
-// Fold does not protect against infinite Iterators.
+// Fold consumes an [Iterator] and returns the final result of applying the
+// accumulator function to each element. The accumulator function accepts two
+// arguments - an accumulator and an initial value and returns a new value for
+// the next accumulation. Fold does not protect against infinite Iterators.
 func Fold[T any, U any](iter Iterator[T], initial U, biop func(U, T) U) U {
 	for {
 		if value, ok := iter.Next().Value(); ok {
@@ -40,9 +40,9 @@ func Fold[T any, U any](iter Iterator[T], initial U, biop func(U, T) U) U {
 	}
 }
 
-// ToChannel consumes an iterator and returns a channel that will receive all
-// values from the provided iterator. The channel is closed once the iterator
-// is exhausted.
+// ToChannel consumes an [Iterator] and returns a channel that will receive all
+// values from the provided [Iterator]. The channel is closed once the
+// [Iterator] is exhausted.
 func ToChannel[T any](iter Iterator[T]) chan T {
 	ch := make(chan T)
 
@@ -61,7 +61,7 @@ func ToChannel[T any](iter Iterator[T]) chan T {
 	return ch
 }
 
-// ForEach consumes an iterator and executes callback function on each item.
+// ForEach consumes an [Iterator] and executes callback function on each item.
 func ForEach[T any](iter Iterator[T], callback func(T)) {
 	for {
 		if value, ok := iter.Next().Value(); ok {
@@ -73,7 +73,7 @@ func ForEach[T any](iter Iterator[T], callback func(T)) {
 }
 
 // Find the first occurrence of a value that satisfies the predicate and return
-// that value. If no value satisfies the predicate, return `None`.
+// that value. If no value satisfies the predicate, return [option.None].
 func Find[T any](iter Iterator[T], predicate func(v T) bool) option.Option[T] {
 	for {
 		if value, ok := iter.Next().Value(); ok {