[release-branch.go1.4] code review 189760043: cmd/go: document import path checking

src/cmd/go/help.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 main
 
 var helpC = &Command{
         UsageLine: "c",
         Short:     "calling between Go and C",
         Long: `
@@ skipping 217 matching lines @@
 
 the go tool will verify that https://example.org/?go-get=1 contains the
 same meta tag and then git clone https://code.org/r/p/exproj into
 GOPATH/src/example.org.
 
 New downloaded packages are written to the first directory
 listed in the GOPATH environment variable (see 'go help gopath').
 
 The go command attempts to download the version of the
 package appropriate for the Go release being used.
-Run 'go help install' for more.
+Run 'go help get' for more.
+
+Import path checking
+
+When the custom import path feature described above redirects to a
+known code hosting site, each of the resulting packages has two possible
+import paths, using the custom domain or the known hosting site.
+
+A package statement is said to have an "import comment" if it is immediately
+followed (before the next newline) by a comment of one of these two forms:
+
+        package math // import "path"
+        package math /* import "path" */
+
+The go command will refuse to install a package with an import comment
+unless it is being referred to by that import path. In this way, import comments
+let package authors make sure the custom import path is used and not a
+direct path to the underlying code hosting site.
+
+See https://golang.org/s/go14customimport for details.
         `,
 }
 
 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.
 
@@ skipping 85 matching lines @@
                 SWIG definition files.
         .syso
                 System object files.
 
 Files of each of these types except .syso may contain build
 constraints, but the go command stops scanning for build constraints
 at the first item in the file that is not a blank line or //-style
 line comment.
         `,
 }