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 <[email protected]>
Reviewed-by: Ian Lance Taylor <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>
Auto-Submit: Ian Lance Taylor <[email protected]>

Author: thediveo

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