maps: Clarify iteration order of Keys & Values and that Insert overwrites existing keys

[magical]

These functions were added in 2b0f2f8 with minimal documentation.

// Keys returns an iterator over keys in m.
func Keys[Map ~map[K]V, K comparable, V any](m Map) iter.Seq[K] {
	...
}

// Values returns an iterator over values in m.
func Values[Map ~map[K]V, K comparable, V any](m Map) iter.Seq[V] {
	...
}

// Insert adds the key-value pairs from seq to m.
func Insert[Map ~map[K]V, K comparable, V any](m Map, seq iter.Seq2[K, V]) {
	...
}

The doc comments should be updated to specify the iteration order of Keys and Values, and the behaviour of Insert when duplicate keys are inserted, per discussion on #61900 and in particular rsc's comment:

Happy to update docs to say that iteration order is undefined (different each time) and Insert does overwrite keys.

[gopherbot]

Change https://go.dev/cl/587015 mentions this issue: maps: clarify iteration order and insertion behavior

[nightlyone]

What happens when keys are added/removed or values changed while iterating might also be interesting to document.

Maybe it should even all be documented once at a package document and the function document should refer to it

[cagedmantis]

cc @ianlancetaylor

[ianlancetaylor]

I agree that we should document iteration order. I'm not yet convinced we need to document the behavior for concurrent inserts and deletes from the map.