Overhaul documentation

iters/chanit/channel.go

@@ -18,6 +18,8 @@ import (
 	"github.com/0x5a17ed/itkit"
 )
 
+// ChannelIterator represents an iterator which yields items retrieved
+// from a Go channel until the channel is closed.
 type ChannelIterator[T any] struct {
 	ch <-chan T
 	v  T
@@ -26,6 +28,8 @@ type ChannelIterator[T any] struct {
 func (it *ChannelIterator[T]) Value() T        { return it.v }
 func (it *ChannelIterator[T]) Next() (ok bool) { it.v, ok = <-it.ch; return }
 
+// In provides an Iterator which yields items retrieved from the
+// given Go channel until the channel is closed.
 func In[T any](ch <-chan T) itkit.Iterator[T] {
 	return &ChannelIterator[T]{ch: ch}
 }

iters/chanit/docs.go

@@ -0,0 +1,20 @@
+// Copyright (c) 2022 Arthur Skowronek <[email protected]>
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// <https://www.apache.org/licenses/LICENSE-2.0>
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package chanit allows for native Go channels to be used with
+// iterators.
+//
+// Iterator functions:
+//   - [In] - yields items retrieved from a native Go channel
+package chanit

iters/funcit/docs.go

@@ -13,5 +13,11 @@
 // limitations under the License.
 
 // Package funcit allows for functional sources of items to be used
-// as streams of data in iterators with the itkit family of functions.
+// with iterators.
+//
+// Iterator functions:
+//   - [IterFn] - calls a [NextFnT] and a [ValueFnT] function to test for more
+//     data and retrieving it
+//   - [PullFn] - calls a single [PullFnT] function to test for more data and
+//     retrieving it
 package funcit

iters/genit/docs.go

@@ -0,0 +1,20 @@
+// Copyright (c) 2022 Arthur Skowronek <[email protected]>
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// <https://www.apache.org/licenses/LICENSE-2.0>
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package genit allows for stateful running goroutines to be used
+// with iterators.
+//
+// Iterator functions:
+//   - [Generator], [GeneratorNoGC] - yields items sent by a running goroutine
+package genit

iters/genit/generator.go

@@ -63,8 +63,8 @@ func (g *G[T]) run(fn GeneratorFn[T]) {
 	fn(g)
 }
 
-// Send is called from a running [GeneratorFn] and sends the given Value to the
-// [Iterator] caller.
+// Send is called from a running [GeneratorFn] and sends the given
+// value to the iterator caller.
 //
 // It panics when the Generator has to stop.
 func (g *G[T]) Send(v T) {
@@ -79,14 +79,14 @@ func newG[T any]() *G[T] {
 	return &G[T]{ch: make(chan T)}
 }
 
-// GIterator represents the receiver facing [Iterator] end of a Generator.
+// GIterator represents the receiver facing Iterator end of a Generator.
 type GIterator[T any] struct {
 	*chanit.ChannelIterator[T]
 	g *G[T]
 }
 
-// Next fetches the next Item produced by the Generator and returns true
-// whenever there is a new item available and false otherwise.
+// Next fetches the next Item produced by the Generator and returns
+// true whenever there is a new item available and false otherwise.
 func (gi *GIterator[T]) Next() bool {
 	if !gi.ChannelIterator.Next() {
 		if gi.g.panic != nil {
@@ -97,7 +97,7 @@ func (gi *GIterator[T]) Next() bool {
 	return true
 }
 
-// Iter returns the underlying [Iterator] of the [GIterator] yielding
+// Iter returns the underlying iterator of the [GIterator] yielding
 // items produced by the generator until the generator function
 // is gone.
 func (gi *GIterator[T]) Iter() itkit.Iterator[T] { return gi }
@@ -115,8 +115,8 @@ func (gi *GIterator[T]) Stop() { gi.g.stop() }
 // Please consider using [Generator] for simplicity reasons unless
 // the Garbage Collector is a concern.
 //
-// The Generator will not be stopped automatically and [itkit.GIterator.Stop]
-// must be called on the returned  to stop the generator manually.
+// The Generator will not be stopped automatically and [genit.GIterator.Stop]
+// must be called on the returned iterator to stop the generator manually.
 //
 // The Generator API is experimental and probably will change.
 func GeneratorNoGC[T any](fn GeneratorFn[T]) *GIterator[T] {

iters/mapit/docs.go

@@ -0,0 +1,22 @@
+// Copyright (c) 2022 Arthur Skowronek <[email protected]>
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// <https://www.apache.org/licenses/LICENSE-2.0>
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package mapit allows for native Go maps to be used with iterators.
+//
+// Iterator functions:
+//   - [In] - yields key-value pairs of a native Go map
+//   - [To] - converts an iterator back to a native Go map
+//   - [Keys] - yields the keys of a native Go map
+//   - [Values] - yields the values of a native Go map
+package mapit

iters/rangeit/docs.go

@@ -0,0 +1,20 @@
+// Copyright (c) 2022 Arthur Skowronek <[email protected]>
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// <https://www.apache.org/licenses/LICENSE-2.0>
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package rangeit allows to iterate over a range of numbers.
+//
+// Iterator functions:
+//   - [Range], [RangeFrom], [RangeStep] - yields numbers in a finite range
+//   - [Count], [CountFrom], [CountStep] - yields continuously increasing numbers
+package rangeit

iters/runeit/docs.go

@@ -0,0 +1,20 @@
+// Copyright (c) 2022 Arthur Skowronek <[email protected]>
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// <https://www.apache.org/licenses/LICENSE-2.0>
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package runeit allows for native Go runes to be used with iterators.
+//
+// Iterator functions:
+//   - [ToString] - convert a rune iterator to a string
+//   - [InString] - provides a rune iterator from a string
+package runeit

iters/sliceit/docs.go

@@ -0,0 +1,21 @@
+// Copyright (c) 2022 Arthur Skowronek <[email protected]>
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// <https://www.apache.org/licenses/LICENSE-2.0>
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package sliceit allows for native Go slices to be used with
+// iterators.
+//
+// Iterator functions:
+//   - [To] - convert a slice iterator to a native Go slice
+//   - [In] - provides an iterator from a native Go slice
+package sliceit

itlib/docs.go

@@ -0,0 +1,16 @@
+// Copyright (c) 2022 Arthur Skowronek <[email protected]>
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// <https://www.apache.org/licenses/LICENSE-2.0>
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package itlib provides generic function for operating on iterators.
+package itlib