spec: poorly documented slice definition syntax

[mtfelian]

What version of Go are you using (go version)?

$ go version
go version go1.11.1 linux/amd64

But also on Windows and in Go 1.12

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

go env Output

$ go env
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/felian/.cache/go-build"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="/home/felian/go_code"
GOPROXY=""
GORACE=""
GOROOT="/usr/local/go"
GOTMPDIR=""
GOTOOLDIR="/usr/local/go/pkg/tool/linux_amd64"
GCCGO="gccgo"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build955872785=/tmp/go-build -gno-record-gcc-switches"

What did you do?

https://play.golang.org/p/clO1qELMYH2

package main
import "fmt"
func main() { fmt.Println([]int{1, 2, 3, 7: 3, 6, 7}) }

Also works nicely with arrays, and with multiple ::

fmt.Println([20]int{1, 2, 3, 7: 11, 12, 13: 10})
fmt.Println([30]int{1, 2, 3, 7: 11, 12, 13: 10, 18: 11, 25})

What did you expect to see?

This syntax should be well documented or invalid.

I found one example of this after "Examples of valid array, slice, and map literals:" in language specification. But it seems not enough.

What did you see instead?

This syntax is valid and seems poorly documented.

Thanks for directions to @irwinnoteam2009

[mvdan]

Ignore my deleted comment; I was looking at the struct section of composite literals.

[ALTree]

It doesn't seem "poorly documented" to me. The spec says, regarding keys in slice literals:

For array and slice literals the following rules apply:

• Each element has an associated integer index marking its position in the array.
• An element with a key uses the key as its index. The key must be a non-negative constant representable by a value of type int; and if it is typed it must be of integer type.
• An element without a key uses the previous element's index plus one. If the first element has no key, its index is zero.

What's missing?

[mtfelian]

It doesn't seem "poorly documented" to me. The spec says, regarding keys in slice literals:

For array and slice literals the following rules apply:

• Each element has an associated integer index marking its position in the array.
• An element with a key uses the key as its index. The key must be a non-negative constant representable by a value of type int; and if it is typed it must be of integer type.
• An element without a key uses the previous element's index plus one. If the first element has no key, its index is zero.

What's missing?

At first i confused it with slicing operator but later noted that it is in { }. In this case we see a sequence of values separated by comma after : symbol. Seems frustrating, what is it. May be only for me? I even did not knew before about this syntax of assigning elements in the slice definition.

[ianlancetaylor]

What do you recommend that we change?

[mtfelian]

What do you recommend that we change?

May be describe it in "Slice expressions" or in "Composite literals" more clearly? I propose:

You can specify values of a slice-typed variable by index while declaring it: 
	a := []int{1, 2, 3,
		4: 10, 20, 30,  // slice part starting at index 4
		10: 100,        // one element at index 10
	}

[ianlancetaylor]

It seems to me that https://golang.org/ref/spec#Composite_literals already says that. As quoted above.

[gopherbot]

Timed out in state WaitingForInfo. Closing.

(I am just a bot, though. Please speak up if this is a mistake or you have the requested information.)