go/importer: document limitations of this API

Arguably it should be deprecated, but that's a process.

Updates #71272

Change-Id: I69de1f9709c45dfea0fe67d96a7bd15d3df4e2f1
Reviewed-on: https://go-review.googlesource.com/c/go/+/643795
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Robert Findley <rfindley@google.com>
Auto-Submit: Alan Donovan <adonovan@google.com>

diff --git a/src/go/importer/importer.go b/src/go/importer/importer.go
index 8a8fb0ec04030bda919dc7d8178bbc7ceca5c77d..54acd7e694020244a22e4809f0c151a2dbdeaa57 100644 (file)
--- a/src/go/importer/importer.go
+++ b/src/go/importer/importer.go
@@ -3,6 +3,13 @@
 // license that can be found in the LICENSE file.
 
 // Package importer provides access to export data importers.
+//
+// These functions, which are mostly deprecated, date from before the
+// introduction of modules in release Go 1.11. They should no longer
+// be relied on except for use in test cases using small programs that
+// depend only on the standard library. For reliable module-aware
+// loading of type information, use the packages.Load function from
+// golang.org/x/tools/go/packages.
 package importer
 
 import (
@@ -79,6 +86,12 @@ func For(compiler string, lookup Lookup) types.Importer {
 
 // Default returns an Importer for the compiler that built the running binary.
 // If available, the result implements [types.ImporterFrom].
+//
+// Default may be convenient for use in the simplest of cases, but
+// most clients should instead use [ForCompiler], which accepts a
+// [token.FileSet] from the caller; without it, all position
+// information derived from the Importer will be incorrect and
+// misleading. See also the package documentation.
 func Default() types.Importer {
        return For(runtime.Compiler, nil)
 }