builtin: update documentation on builtin make #22764
Description
Please answer these questions before submitting your issue. Thanks!
What version of Go are you using (go version)?
1.9.2
Does this issue reproduce with the latest release?
Yes
What operating system and processor architecture are you using (go env)?
darwin amd64
What did you do?
If possible, provide a recipe for reproducing the error.
A complete runnable program is good.
A link on play.golang.org is best.
read the documentation on the make builtin (https://golang.org/pkg/builtin/#make)
What did you expect to see?
An explanation that specifying the capacity for a slice means that go will allocate an array big enough to hold that capacity without any resizing.
(After digging around the source code, I found this to be true)
What did you see instead?
Ambiguous comment:
// Slice: The size specifies the length. The capacity of the slice is
// equal to its length. A second integer argument may be provided to
// specify a different capacity; it must be no smaller than the
// length, so make([]int, 0, 10) allocates a slice of length 0 and
// capacity 10.
Proposed Fix
Update this section of the comment to read:
// Slice: The size specifies the length. The capacity of the slice is
// equal to its length. A second integer argument may be provided to
// specify a different capacity; it must be no smaller than the
// length, so make([]int, 0, 10) allocates an underlying array of size 10
// and returns a slice of length 0 and capacity 10 that is backed by this
// underlying array.