iter: documentation improvements

[3052]

Proposal Details

these

https://go.dev/pkg/iter/?m=old#Seq
https://go.dev/pkg/iter/?m=old#Seq2

both say this

"See the iter package documentation for more details" and link back to the same page:

https://go.dev/pkg/iter

also, the entire page does not give an example of implementing either type. technically yes, it does have the below example, but not an example of creating iter.Seq, and even the given example has a iter.Seq as input, so it would assume that you have already implemented iter.Seq without giving an example on how to do so

func Pairs[V any](seq iter.Seq[V]) iter.Seq2[V, V] {
	return func(yield func(V, V) bool) {
		next, stop := iter.Pull(seq)
		defer stop()
		for {
			v1, ok1 := next()
			if !ok1 {
				return
			}
			v2, ok2 := next()
			// If ok2 is false, v2 should be the
			// zero value; yield one last pair.
			if !yield(v1, v2) {
				return
			}
			if !ok2 {
				return
			}
		}
	}
}

[gabyhelp]

Related Issues

• iter: example Pairs in package doc uses wrong (outdated?) signature for iter.Seq2 #68056 (closed)
• iter: Pull example in package doc loops forever #68073 (closed)
• proposal: iter: Enumerate, Keys and Values functions #68887 (closed)
• iter: new package for iterators #61897 (closed)
• proposal: iter: convert between Seq and Seq2 #67334
• proposal: Go 2: iterators #40605 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[3052]

here is an example from maps

func Keys[Map ~map[K]V, K comparable, V any](m Map) iter.Seq[K] {
	return func(yield func(K) bool) {
		for k := range m {
			if !yield(k) {
				return
			}
		}
	}
}

[Jorropo]

Reading the links you sent the example you show is meant to demonstrate iter.Pull and I find it for it's use of iter.Pull but it's the goal so ¯\_(ツ)_/¯
If you have ideas on how to improve the docs a patch would be welcome https://go.dev/doc/contribute but I'm not sure how it should look.

[3052]

I think Ive made it pretty clear already what the issues are, and what a fix could look like - so I don't think I need to add anything further

[thediveo]

The referenced docs have this paragraph

Iterator functions are most often called by a range loop, as in:

Admittedly upon encountering this for the first time I thought "but how do I write one, so I can use it?"

Would it be fine to do a PR that inserts a new paragraph and a short code before the above paragraph? Like a simple iterator over a slice just for simple illustration?