go/build: document GOPATH

Fixes #2332.

R=golang-dev, remyoudompheng, gri, r, r
CC=golang-dev
https://golang.org/cl/5710055

src/cmd/go/help.go

@@ -138,6 +138,9 @@ var helpGopath = &Command{
 	UsageLine: "gopath",
 	Short:     "GOPATH environment variable",
 	Long: `
+The Go path is used to resolve import statements.
+It is implemented by and documented in the go/build package.
+
 The GOPATH environment variable lists places to look for Go code.
 On Unix, the value is a colon-separated string.
 On Windows, the value is a semicolon-separated string.

src/pkg/go/build/build.go

@@ -6,7 +6,54 @@
 //
 // Go Path
 //
-// TODO: Document GOPATH.
+// 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
+// Go tree.  The default path is the value of the GOPATH environment
+// variable, interpreted as a path list appropriate to the operating system
+// (on Unix, the variable is a colon-separated string;
+// on Windows, a semicolon-separated string;
+// on Plan 9, a list).
+//
+// Each directory listed in the Go path must have a prescribed structure:
+//
+// The src/ directory holds source code.  The path below 'src' determines
+// the import path or executable name.
+//
+// The pkg/ directory holds installed package objects.
+// As in the Go tree, each target operating system and
+// architecture pair has its own subdirectory of pkg
+// (pkg/GOOS_GOARCH).
+// 
+// If DIR is a directory listed in the Go path, a package with
+// source in DIR/src/foo/bar can be imported as "foo/bar" and
+// has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a"
+// (or, for gccgo, "DIR/pkg/gccgo/foo/libbar.a").
+// 
+// The bin/ directory holds compiled commands.
+// Each command is named for its source directory, but only
+// using the final element, not the entire path.  That is, the
+// command with source in DIR/src/foo/quux is installed into
+// DIR/bin/quux, not DIR/bin/foo/quux.  The foo/ is stripped
+// so that you can add DIR/bin to your PATH to get at the
+// installed commands.
+// 
+// Here's an example directory layout:
+// 
+//	GOPATH=/home/user/gocode
+// 
+//	/home/user/gocode/
+//	    src/
+//	        foo/
+//	            bar/               (go code in package bar)
+//	                x.go
+//	            quux/              (go code in package main)
+//	                y.go
+//	    bin/
+//	        quux                   (installed command)
+//	    pkg/
+//	        linux_amd64/
+//	            foo/
+//	                bar.a          (installed package object)
 //
 // Build Constraints
 //