slices: unclear documentations

Dissimilar to the corresponding data structures in other languages such as vector in C++ or ArrayList in Java, a Go slice does not own the data it contains but is a mere mutable view over a backing array. As a result, slices can share a common backing array and changes made to the data through one can be observable by the others. This requires operations mutating the data of a slice expressing their behaviour clearly and covering all cases, which seems to be absent from the slices package.

Suggestions:

  // 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 operates as if it reads all data from s and v before doing
+ // any modification.
+ // Insert creates a new backing array and leaves
+ // the existing ones unchanged if len(s) + len(v) > cap(s)
+ // Otherwise, it modifies the backing array of s and the
+ // returned slice has the same backing array as s
  // Insert panics if i is out of range.
  // This function is O(len(s) + len(v)).
  func Insert[S ~[]E, E any](s S, i int, v ...E) S

  // Delete removes the elements s[i:j] from s, returning the modified slice.
  // Delete panics if s[i:j] is not a valid slice of s.
- // Delete modifies the contents of the slice s; it does not create a new slice.
+ // Delete modifies the contents of the backing array of s, it does not create
+ // a new backing array, the returned slice has the same backing array as s.
+ // Delete operates as if it reads all data from s before doing any modification.
  // Delete is O(len(s)-j), so if many items must be deleted, it is better to
  // make a single call deleting them all together than to delete one at a time.
- // Delete might not modify the elements s[len(s)-(j-i):len(s)]. If those
+ // Delete does not modify the elements s[len(s)-(j-i):len(s)]. If those 
  // elements contain pointers you might consider zeroing those elements so that
  // objects they reference can be garbage collected.
  func Delete[S ~[]E, E any](s S, i, j int) S

  // DeleteFunc removes any elements from s for which del returns true,
  // returning the modified slice.
- // DeleteFunc modifies the contents of the slice s;
- // it does not create a new slice.
- // When DeleteFunc removes m elements, it might not modify the elements
+ // DeleteFunc operates as if it reads all data from s before doing any modification
+ // DeleteFunc modifies the contents of the backing array of s, it does not create
+ // a new backing array, the returned slice has the same backing array as s.
+ // When DeleteFunc removes m elements, it does not modify the elements
  // s[len(s)-m:len(s)]. If those elements contain pointers you might consider
  // zeroing those elements so that objects they reference can be garbage
  // collected.
  func DeleteFunc[S ~[]E, E any](s S, del func(E) bool) S

  // Replace replaces the elements s[i:j] by the given v, and returns the
- // modified slice. Replace panics if s[i:j] is not a valid slice of s.
+ // Replace operates as if it reads all data from s and v before doing
+ // any modification.
+ // Replace creates a new backing array and leaves the existing ones
+ // unchanged if len(s) - (j-i) + len(v) > cap(s),
+ // Otherwise, it modifies the backing array of s and the
+ // returned slice has the same backing array as s.
+ // Replace panics if s[i:j] is not a valid slice of s.
  func Replace[S ~[]E, E any](s S, i, j int, v ...E) S

- // Clone returns a copy of the slice.
+ // Clone returns a new slice with the same elements as those of s
+ // with a newly created backing array.
  // The elements are copied using assignment, so this is a shallow clone.
  func Clone[S ~[]E, E any](s S) S

  // Compact replaces consecutive runs of equal elements with a single copy.
  // This is like the uniq command found on Unix.
- // Compact modifies the contents of the slice s; it does not create a new slice.
- // When Compact discards m elements in total, it might not modify the elements
+ // Compact operates as if it reads all data from s and v before doing
+ // any modification.
+ // Compact modifies the contents of the backing array of s, it does not create a
+ // new backing array, the returned slice has the same backing array as s.
+ // When Compact discards m elements in total, it does not modify the elements
  // s[len(s)-m:len(s)]. If those elements contain pointers you might consider
  // zeroing those elements so that objects they reference can be garbage collected.
  func Compact[S ~[]E, E comparable](s S) S

  // Grow increases the slice's capacity, if necessary, to guarantee space for
  // another n elements. After Grow(n), at least n elements can be appended
- // to the slice without another allocation. If n is negative or too large to
- // allocate the memory, Grow panics.
+ // Grows creates a new backing array if len(s) + n > cap(s), in which case
+ // the returned slice has a different backing array from s.
+ // Otherwise, Grows returns s unchanged.
+ // If n is negative or too large to allocate the memory, Grow panics.
 func Grow[S ~[]E, E any](s S, n int) S

  // Clip removes unused capacity from the slice, returning s[:len(s):len(s)].
+ // Clip does not modify the backing array of s.
  func Clip[S ~[]E, E any](s S) S