code review 9064044: go/build: document GOOS.go also has implicit GOOS build...

src/pkg/go/build/doc.go

 // Copyright 2011 The Go Authors.  All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
 // Package build gathers information about Go packages.
 //
 // Go Path
 //
 // The Go path is a list of directory trees containing Go source code.
 // It is consulted to resolve imports that cannot be found in the standard
@@ skipping 79 matching lines @@
 // During a particular build, the following words are satisfied:
 //
 //      - the target operating system, as spelled by runtime.GOOS
 //      - the target architecture, as spelled by runtime.GOARCH
 //      - the compiler being used, either "gc" or "gccgo"
 //      - "cgo", if ctxt.CgoEnabled is true
 //      - "go1.1", from Go version 1.1 onward
 //      - any additional words listed in ctxt.BuildTags
 //
 // If a file's name, after stripping the extension and a possible _test suffix,
-// matches GOOS, GOARCH, *_GOOS, *_GOARCH, or *_GOOS_GOARCH for any known operating
-// system and architecture values, then the file is considered to have an implicit
-// build constraint requiring those terms.
+// matches any of the following patterns:
+//      *_GOOS
+//      *_GOARCH
+//      *_GOOS_GOARCH
+// (example: source_windows_amd64.go) or the literals:
+//      GOOS
+//      GOARCH
+// (example: windows.go) where GOOS and GOARCH represent any known operating
+// system and architecture values respectively, then the file is considered to
+// have an implicit build constraint requiring those terms.
 //
 // To keep a file from being considered for the build:
 //
 //      // +build ignore
 //
 // (any other unsatisfied word will work as well, but ``ignore'' is conventional.)
 //
 // To build a file only when using cgo, and only on Linux and OS X:
 //
 //      // +build linux,cgo darwin,cgo
 //
 // Such a file is usually paired with another file implementing the
 // default functionality for other systems, which in this case would
 // carry the constraint:
 //
 //      // +build !linux,!darwin !cgo
 //
 // Naming a file dns_windows.go will cause it to be included only when
 // building the package for Windows; similarly, math_386.s will be included
 // only when building the package for 32-bit x86.
 //
 package build