cmd/go, go/build: clarify build constraint docs

Clarify that the //go:build line is an expression of constraints,
not a constraint itself.

Fixes #53308

Change-Id: Ib67243c6ee5cfe3b688c12b943b5e7496f686035
Reviewed-on: https://go-review.googlesource.com/c/go/+/411697
Reviewed-by: Rob Pike <r@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>
Run-TryBot: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Run-TryBot: Ian Lance Taylor <iant@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
Reviewed-by: David Chase <drchase@google.com>

src/cmd/go/alldocs.go

@@ -195,11 +195,10 @@
 //		For example, when building with a non-standard configuration,
 //		use -pkgdir to keep generated packages in a separate location.
 //	-tags tag,list
-//		a comma-separated list of build tags to consider satisfied during the
+//		a comma-separated list of additional build tags to consider satisfied
-//		build. For more information about build tags, see the description of
+//		during the build. For more information about build tags, see
-//		build constraints in the documentation for the go/build package.
+//		'go help buildconstraint'. (Earlier versions of Go used a
-//		(Earlier versions of Go used a space-separated list, and that form
+//		space-separated list, and that form is deprecated but still recognized.)
-//		is deprecated but still recognized.)
 //	-trimpath
 //		remove all file system paths from the resulting executable.
 //		Instead of absolute file system paths, the recorded file names
@@ -1797,11 +1796,12 @@
 //
 // # Build constraints
 //
-// A build constraint, also known as a build tag, is a line comment that begins
+// A build constraint, also known as a build tag, is a condition under which a
+// file should be included in the package. Build constraints are given by a
+// line comment that begins
 //
 //	//go:build
 //
-// that lists the conditions under which a file should be included in the package.
 // Constraints may appear in any kind of source file (not just Go), but
 // they must appear near the top of the file, preceded
 // only by blank lines and other line comments. These rules mean that in Go
@@ -1810,9 +1810,9 @@
 // To distinguish build constraints from package documentation,
 // a build constraint should be followed by a blank line.
 //
-// A build constraint is evaluated as an expression containing options
+// A build constraint comment is evaluated as an expression containing
-// combined by ||, &&, and ! operators and parentheses. Operators have
+// build tags combined by ||, &&, and ! operators and parentheses.
-// the same meaning as in Go.
+// Operators have the same meaning as in Go.
 //
 // For example, the following build constraint constrains a file to
 // build when the "linux" and "386" constraints are satisfied, or when
@@ -1822,7 +1822,7 @@
 //
 // It is an error for a file to have more than one //go:build line.
 //
-// During a particular build, the following words are satisfied:
+// During a particular build, the following build tags are satisfied:
 //
 //   - the target operating system, as spelled by runtime.GOOS, set with the
 //     GOOS environment variable.

src/cmd/go/internal/help/helpdoc.go

@@ -812,11 +812,12 @@ var HelpBuildConstraint = &base.Command{
 	UsageLine: "buildconstraint",
 	Short:     "build constraints",
 	Long: `
-A build constraint, also known as a build tag, is a line comment that begins
+A build constraint, also known as a build tag, is a condition under which a
+file should be included in the package. Build constraints are given by a
+line comment that begins
 
 	//go:build
 
-that lists the conditions under which a file should be included in the package.
 Constraints may appear in any kind of source file (not just Go), but
 they must appear near the top of the file, preceded
 only by blank lines and other line comments. These rules mean that in Go
@@ -825,9 +826,9 @@ files a build constraint must appear before the package clause.
 To distinguish build constraints from package documentation,
 a build constraint should be followed by a blank line.
 
-A build constraint is evaluated as an expression containing options
+A build constraint comment is evaluated as an expression containing
-combined by ||, &&, and ! operators and parentheses. Operators have
+build tags combined by ||, &&, and ! operators and parentheses.
-the same meaning as in Go.
+Operators have the same meaning as in Go.
 
 For example, the following build constraint constrains a file to
 build when the "linux" and "386" constraints are satisfied, or when
@@ -837,7 +838,7 @@ build when the "linux" and "386" constraints are satisfied, or when
 
 It is an error for a file to have more than one //go:build line.
 
-During a particular build, the following words are satisfied:
+During a particular build, the following build tags are satisfied:
 
 	- the target operating system, as spelled by runtime.GOOS, set with the
 	  GOOS environment variable.

src/cmd/go/internal/work/build.go

@@ -151,11 +151,10 @@ and test commands:
 		For example, when building with a non-standard configuration,
 		use -pkgdir to keep generated packages in a separate location.
 	-tags tag,list
-		a comma-separated list of build tags to consider satisfied during the
+		a comma-separated list of additional build tags to consider satisfied
-		build. For more information about build tags, see the description of
+		during the build. For more information about build tags, see
-		build constraints in the documentation for the go/build package.
+		'go help buildconstraint'. (Earlier versions of Go used a
-		(Earlier versions of Go used a space-separated list, and that form
+		space-separated list, and that form is deprecated but still recognized.)
-		is deprecated but still recognized.)
 	-trimpath
 		remove all file system paths from the resulting executable.
 		Instead of absolute file system paths, the recorded file names

src/go/build/doc.go

@@ -57,12 +57,13 @@
 //
 // # Build Constraints
 //
-// A build constraint, also known as a build tag, is a line comment that begins
+// A build constraint, also known as a build tag, is a condition under which a
+// file should be included in the package. Build constraints are given by a
+// line comment that begins
 //
 //	//go:build
 //
-// that lists the conditions under which a file should be included in the
+// Build constraints may also be part of a file's name
-// package. Build constraints may also be part of a file's name
 // (for example, source_windows.go will only be included if the target
 // operating system is windows).
 //