slices: document two oddities

Fixes #70935

Change-Id: Idf4a38a05ba595d616b6469a14419ff873bbd354
Reviewed-on: https://go-review.googlesource.com/c/go/+/638095
Reviewed-by: Keith Randall <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>
Reviewed-by: Keith Randall <[email protected]>
Reviewed-by: Ian Lance Taylor <[email protected]>

Author: adonovan

src/slices/slices.go

@@ -414,6 +414,7 @@ func Grow[S ~[]E, E any](s S, n int) S {
 		panic("cannot be negative")
 	}
 	if n -= cap(s) - len(s); n > 0 {
+		// This expression allocates only once (see test).
 		s = append(s[:cap(s)], make([]E, n)...)[:len(s)]
 	}
 	return s
@@ -483,6 +484,9 @@ func Concat[S ~[]E, E any](slices ...S) S {
 			panic("len out of range")
 		}
 	}
+	// Use Grow, not make, to round up to the size class:
+	// the extra space is otherwise unused and helps
+	// callers that append a few elements to the result.
 	newslice := Grow[S](nil, size)
 	for _, s := range slices {
 		newslice = append(newslice, s...)