cmd/go: confusing documentation on build tags

[gazerro]

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

go1.18.3

Does this issue reproduce with the latest release?

Yes.

What did you do?

The go command documentation (https://pkg.go.dev/cmd/go@master) reports

-tags tag,list
	a comma-separated list of build tags to consider satisfied during the
	build. For more information about build tags, see the description of
	build constraints in the documentation for the go/build package.

So tag and list in the example are called "build tags". I open the description of build constraints in the go/build package documentation (https://pkg.go.dev/go/build#hdr-Build_Constraints) and it reports:

A build constraint, also known as a build tag, is a line comment that begins

//go:build

So the tag option of the go command wants a list of line comments? And which "build tags" can be used with the go command?

What did you expect to see?

The values ​​that can be used for the tag option of the go command.

What did you see instead?

Confusing documentation on build tags.

[seankhliao]

go/build links to https://pkg.go.dev/cmd/go#hdr-Build_constraints for details.

[gazerro]

@seankhliao cmd/go says to read go/build and go/build link back to cmd/go and even this latest documentation does not resolve what I have indicated in this issue.

[fzipp]

I'd say the "also known as a build tag" part is wrong. "darwin" and "cgo" are build tags, the whole //go:build line is a build constraint using build tags, but not a build tag itself.

[fzipp]

This was added on purpose: https://codereview.appspot.com/44100043
Contrary to the commit message I don't think it made things clearer.

[cherrymui]

cc @rsc @bcmills

[gopherbot]

Change https://go.dev/cl/411697 mentions this issue: cmd/go, go/build: clarify build constraint docs

[gazerro]

To clarify, I would also suggest adding the term "additional" to the documentation of the -tags flag

a comma-separated list of additional build tags to consider satisfied during the build.

as already used in the build constraints documentation by referring to the -tags flag.

[ianlancetaylor]

@gazerro Thanks, I made that change in https://go.dev/cl/411697.

[gazerro]

@ianlancetaylor Thanks. I just noticed a typo in the same line, 'go help buildconstraints' should be 'go help buildconstraint'.

[ianlancetaylor]

@gazerro Thanks, fixed.