iter: add more examples

[samsonkolge]

Proposal Details

Background

The iter package was introduced in Go 1.22 as a new standard library package
for working with iterators. It provides important abstractions like Seq and
Seq2 types, along with the Pull and Pull2 functions.

Currently, the package has comprehensive documentation in the comment blocks,
but lacks an example_test.go file with concrete, runnable examples. This
makes it harder for users to understand the idiomatic usage patterns for
iterators, especially for the Pull functions.

Proposal

Add an example_test.go file to the iter package that demonstrates:

1. Basic usage of Seq and Seq2 iterators
2. How to properly create and consume iterators with range loops
3. How to use Pull and Pull2 functions, including proper resource cleanup
4. Common patterns for chaining and transforming iterators
5. Examples of creating custom iterators

Expected Benefits

Having clear, runnable examples will:

• Help users understand the iterator patterns more concretely
• Demonstrate best practices for iterator usage (such as proper cleanup)
• Provide copy-pastable code examples for common use cases
• Complement the existing documentation with practical implementations

These examples would be especially helpful for this new package as developers
are still learning the idiomatic ways to use iterators in Go.

Implementation Plan

I'm willing to implement this improvement by creating a new example_test.go
file with comprehensive examples if the proposal is accepted.

/cc @golang/docs

[gopherbot]

Change https://go.dev/cl/664137 mentions this issue: docs: add examples for iter package

[gabyhelp]

Related Issues

• iter: documentation improvements #70986 (closed)
• iter: new package for iterators #61897 (closed)
• proposal: Go 2: iterators #40605 (closed)

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