iter: improve documentation with iterator example

In introducing iterators, package iter gives an example of how to
use an iterator in a range-over-func loop, but currently does not
give an example of what an iterator implementation might look like.

This change adds the example of map.Keys() before the usage example.
Additionally, it references to the Go blog for further examples,
as well as the language spec about for-range loops.

Fixes #70986

Change-Id: I7108d341d314d7de146b4c221700736c943a9f5d
Reviewed-on: https://go-review.googlesource.com/c/go/+/638895
Reviewed-by: Cherry Mui <cherryyz@google.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>

diff --git a/src/iter/iter.go b/src/iter/iter.go
index 14fd8f8115f3f6f73d0b3d8f284d263b68c657f6..e765378ef25f45b0c0329c7697ba2bd33e2d0cea 100644 (file)
--- a/src/iter/iter.go
+++ b/src/iter/iter.go
@@ -28,7 +28,22 @@ or index-value pairs.
 Yield returns true if the iterator should continue with the next
 element in the sequence, false if it should stop.
 
-Iterator functions are most often called by a range loop, as in:
+For instance, [maps.Keys] returns an iterator that produces the sequence
+of keys of the map m, implemented as follows:
+
+       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
+                               }
+                       }
+               }
+       }
+
+Further examples can be found in [The Go Blog: Range Over Function Types].
+
+Iterator functions are most often called by a [range loop], as in:
 
        func PrintAll[V any](seq iter.Seq[V]) {
                for v := range seq {
@@ -187,6 +202,9 @@ And then a client could delete boring values from the tree using:
                        p.Delete()
                }
        }
+
+[The Go Blog: Range Over Function Types]: https://go.dev/blog/range-functions
+[range loop]: https://go.dev/ref/spec#For_range
 */
 package iter