gopls/internal/lsp/cache: expand ImportPath!=PackagePath comment
Change-Id: I2ea748a6a434bada2a310581538ac5d8dcefa01e
Reviewed-on: https://go-review.googlesource.com/c/tools/+/454562
Auto-Submit: Alan Donovan <adonovan@google.com>
Reviewed-by: Robert Findley <rfindley@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Run-TryBot: Alan Donovan <adonovan@google.com>
diff --git a/gopls/internal/lsp/cache/load.go b/gopls/internal/lsp/cache/load.go
index ccba4e8..19b21c6 100644
--- a/gopls/internal/lsp/cache/load.go
+++ b/gopls/internal/lsp/cache/load.go
@@ -552,6 +552,30 @@
// (Beware that, for historical reasons, go list uses
// the JSON field "ImportPath" for the package's
// path--effectively the linker symbol prefix.)
+ //
+ // The example above is slightly special to go list
+ // because it's in the std module. Otherwise,
+ // vendored modules are simply modules whose directory
+ // is vendor/ instead of GOMODCACHE, and the
+ // import path equals the package path.
+ //
+ // But in GOPATH (non-module) mode, it's possible for
+ // package vendoring to cause a non-identity ImportMap,
+ // as in this example:
+ //
+ // $ cd $HOME/src
+ // $ find . -type f
+ // ./b/b.go
+ // ./vendor/example.com/a/a.go
+ // $ cat ./b/b.go
+ // package b
+ // import _ "example.com/a"
+ // $ cat ./vendor/example.com/a/a.go
+ // package a
+ // $ GOPATH=$HOME GO111MODULE=off go list -json ./b | grep -A2 ImportMap
+ // "ImportMap": {
+ // "example.com/a": "vendor/example.com/a"
+ // },
// Don't remember any imports with significant errors.
//
