slices: clarify Insert append behavior #69104
Description
The documentation for the slices.Insert function does not clearly indicate that it also allows appending new values:
Insert inserts the values v... into s at index i, returning the modified slice. The elements at s[i:] are shifted up to make room. In the returned slice r, r[i] == v[0], and r[i+len(v)] == value originally at r[i]. Insert panics if i is out of range. This function is O(len(s) + len(v)).
The behavior is correct and matches my expectations. However, if i == len(s), stating that i cannot be out of range does not clarify this aspect. Furthermore, asserting that r[i+len(v)] == value originally at r[i] is not helpful because in this case r[i] is out of range and therefore invalid.