bytes: document capacity expectations of Split and Fields

[dsnet]

The Split function returns a slice of sub-slices from the original input. Presently, it does not document any expectations regarding the capacity of each individual sub-slice.

For example, what's the expected behavior of the following?

lines := bytes.Split([]byte("foo\nbar\n", []byte("\n"))
lines[0] = append(lines[0], "XXXXX"...)
fmt.Println(lines[1]) // does this print "bar" or "XXX"?

Currently, it prints "bar" because the logic explicitly caps the capacity to the length, which is the behavior I would expect.
However, we should probably document that this is behavior users can depend on.

[zigo101]

similar to #43341

[zigo101]

We could write the append line as

lines[0] = append(lines[0][:len(lines[0]):len(lines[0])], "XXXXX"...)

but it is too verbose, which might be a reason why people don't like using three-iindex slice form.
Some proposals to remove the verbosity:

• proposal: spec: allow append(string, ...) and view the string argument as a byte slice #43429: append(string(lines[0]), "XXXXX"...)
• proposal: Go 2: make final index in a three-index slice expression default to the middle index value #25638: append(lines[0][::], "XXXXX"...)

[cagedmantis]

/cc @bradfitz @ianlancetaylor