comments in examples

example_test.go

@@ -14,6 +14,8 @@ func ExampleNew() {
 	arr := [5]int{5, 10, 15, 20, 25}
 	var idx int
 
+	// function to manually iterator over slice.
+	// It is more comfortable to use itertools.NewSliceIterator in this case
 	f := func() (int, bool) {
 		if idx >= len(arr) {
 			return 0, false
@@ -170,6 +172,7 @@ func ExampleIterator_Collect() {
 	s := []string{"First", "Second", "Third"}
 	idx := len(s) - 1
 
+	// function to iterate over slice in reverse order
 	f := func() (string, bool) {
 		if idx < 0 {
 			return "", false
@@ -435,8 +438,8 @@ func ExampleEnumerate() {
 	iter := itertools.Enumerate(itertools.NewSliceIterator(people))
 
 	for iter.Next() {
-		elem := iter.Elem()
-		fmt.Printf("Index: %d ||| Name: %s ||| Age: %d\n", elem.Second, elem.First.Name, elem.First.Age)
+		person, i := iter.Elem().Unpack()
+		fmt.Printf("Index: %d ||| Name: %s ||| Age: %d\n", i, person.Name, person.Age)
 	}
 	// Output:
 	// Index: 0 ||| Name: Bob ||| Age: 31
@@ -566,6 +569,7 @@ func ExampleNewMapIterator() {
 		return slices.Contains(summerMonths, p.Second)
 	})
 
+	// iterating over map keys (months numbers) rather than entire key-value pairs
 	numbersIter := itertools.Map(iter, func(p itertools.Pair[int, string]) int {
 		return p.First
 	})

mapfilter_example_test.go

@@ -7,15 +7,18 @@ import (
 	"time"
 )
 
+// imitating account name or something
 type Account string
 
+// stub representation of financial transaction
 type Transaction struct {
 	From      Account
 	To        Account
 	Amount    int
 	Timestamp time.Time
 }
 
+// stub representation of transaction message from message queue
 type Message struct {
 	FromTo string
 	Amount int
@@ -31,6 +34,7 @@ func messageToTransaction(msg Message) Transaction {
 	return tx
 }
 
+// mock fraud checker for financial transactions
 type FraudChecker struct {
 	definitelyFraudulent Account
 }
@@ -39,6 +43,7 @@ func (fc *FraudChecker) IsFraudulentTransaction(tx Transaction) bool {
 	return tx.To == fc.definitelyFraudulent || tx.From == fc.definitelyFraudulent
 }
 
+// mock fraud transaction alerter
 type Alerter struct{}
 
 func (Alerter) Alert(tx Transaction) {
@@ -50,8 +55,10 @@ func (Alerter) Alert(tx Transaction) {
 	fmt.Println(sb.String())
 }
 
+// mock consumer of message queue/broker
 type MessageConsumer []Message
 
+// imitating process of message consumption
 func (mc *MessageConsumer) StartConsume() <-chan Message {
 	messages := make([]Message, len(*mc))
 	copy(messages, *mc)
@@ -110,8 +117,11 @@ func Example_mapFilter() {
 	alerter := Alerter{}
 
 	iter := itertools.Map(
+		// iterating over messages
 		itertools.NewChanIterator(ch),
+		// mapping them to transactions
 		messageToTransaction,
+		// keeping only fraudulent ones
 	).Filter(fraudChecker.IsFraudulentTransaction)
 
 	iter.Range(func(tx Transaction) bool {

mapreduce_example_test.go

@@ -14,9 +14,12 @@ func Example_mapReduce() {
 
 	stddev := itertools.
 		Map(
+			// iterating over data
 			itertools.NewSliceIterator(data),
+			// transforming data from int to float64
 			func(n int) float64 { return float64(n) },
 		).
+		// calculating standard deviation of data
 		Reduce(0, func(acc float64, elem float64) float64 {
 			return acc + (elem-avg)*(elem-avg)
 		})

set_example_test.go

@@ -16,7 +16,9 @@ func Example_set() {
 	const batchSize = 2500
 
 	iter := itertools.
+		// batching incoming values into batches with size batchSize (2500)
 		Batched(itertools.NewMapKeysIterator(values).
+			// keeping only numbers divisible by 4
 			Filter(func(n int) bool { return n%4 == 0 }),
 			batchSize)
 
@@ -40,6 +42,7 @@ func Example_set() {
 }
 
 func process(values []int) {
+	// long processing imitation
 	time.Sleep(time.Duration(len(values)) * time.Microsecond)
 	fmt.Printf("processed %d items\n", len(values))
 }