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.

[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?

[cherrymui]

Feel free to send a CL to improve the documentation, and/or add examples. Thanks!

Also, it probably makes sense to have a link to the language spec's range over function part.

[ianlancetaylor]

The blog post https://go.dev/blog/range-functions also gives some examples of writing iterators.

I'm not sure how much should be added to the package documentation. It's hard to know when to stop. The right approach might be to add a few Example functions.

[thediveo]

My current change is to have the maps.Keys iterator example as this is small enough, yet up to the point. The link to the for loop language spec also snugly fits in with the existing paragraph about "...often called by a range loop, as in...". Linking to more examples in the blog will IMHO also neatly fit in without overcrowding.

[gopherbot]

Change https://go.dev/cl/638895 mentions this issue: iter: improve documentation with iterator example

[thediveo]

Note that the self reference actually points to the package documentation that the CL improves. Feel free to submit your CL.

[ianlancetaylor]

When I click on the link, it brings me to the top of the page. This doesn't seem unreasonable.

[ianlancetaylor]

@3052 Understood, but it still seems OK to me as it currently is.