cmd/cgo: explicitly state that #cgo directives across multiple files are concatenated

This is a quick documentation change/clarification, as this
confused me before: in my own cgo-based projects, I currently have
identical #cgo directives in each relevant source file, and I notice
with go build -x that cgo is combining the directives, leading to
pkg-config invocations with the same package name (gtk+-3.0, in my
case) repeated several times, or on Mac OS X, LDFLAGS listing
-framework Foundation -framework AppKit multiple times. Since I am
about to add a CFLAGS as well, I checked the source to cmd/cgo and
go/build (where the work is actually done) to see if that still holds
true there. Hopefully other people who have made the same mistake I
have (I don't know if anyone has) can remove the excess declarations
now; this should make things slightly easier to manage as well.

LGTM=iant
R=golang-codereviews, gobot, iant
CC=golang-codereviews
https://golang.org/cl/91520046

src/cmd/cgo/doc.go

@@ -52,6 +52,14 @@ these directives.  Package-specific flags should be set using the
 directives, not the environment variables, so that builds work in
 unmodified environments.
 
+All the cgo CPPFLAGS and CFLAGS directives in a package are concatenated and
+used to compile C files in that package.  All the CPPFLAGS and CXXFLAGS
+directives in a package are concatenated and used to compile C++ files in that
+package.  All the LDFLAGS directives in any package in the program are
+concatenated and used at link time.  All the pkg-config directives are
+concatenated and sent to pkg-config simultaneously to add to each appropriate
+set of command-line flags.
+
 When the Go tool sees that one or more Go files use the special import
 "C", it will look for other non-Go files in the directory and compile
 them as part of the Go package.  Any .c, .s, or .S files will be