go/packages: improve docs of 'go list' and GOPACKAGESDRIVER

Fixes golang/go#34341
Updates golang/go#64608

Change-Id: I3b41660c12942fdb15b8ea6f1f3c0b77ae91b897
Reviewed-on: https://go-review.googlesource.com/c/tools/+/547977
LUCI-TryBot-Result: Go LUCI <[email protected]>
Reviewed-by: Michael Matloob <[email protected]>
Auto-Submit: Alan Donovan <[email protected]>

Author: adonovan

go/packages/doc.go

@@ -5,12 +5,32 @@
 /*
 Package packages loads Go packages for inspection and analysis.
 
-The Load function takes as input a list of patterns and return a list of Package
-structs describing individual packages matched by those patterns.
-The LoadMode controls the amount of detail in the loaded packages.
-
-Load passes most patterns directly to the underlying build tool,
-but all patterns with the prefix "query=", where query is a
+The [Load] function takes as input a list of patterns and returns a
+list of [Package] values describing individual packages matched by those
+patterns.
+A [Config] specifies configuration options, the most important of which is
+the [LoadMode], which controls the amount of detail in the loaded packages.
+
+Load passes most patterns directly to the underlying build tool.
+The default build tool is the go command.
+Its supported patterns are described at
+https://pkg.go.dev/cmd/go#hdr-Package_lists_and_patterns.
+
+Load may be used in Go projects that use alternative build systems, by
+installing an appropriate "driver" program for the build system and
+specifying its location in the GOPACKAGESDRIVER environment variable.
+For example,
+https://github.com/bazelbuild/rules_go/wiki/Editor-and-tool-integration
+explains how to use the driver for Bazel.
+The driver program is responsible for interpreting patterns in its
+preferred notation and reporting information about the packages that
+they identify.
+(See driverRequest and driverResponse types for the JSON
+schema used by the protocol.
+Though the protocol is supported, these types are currently unexported;
+see #64608 for a proposal to publish them.)
+
+Regardless of driver, all patterns with the prefix "query=", where query is a
 non-empty string of letters from [a-z], are reserved and may be
 interpreted as query operators.
 
@@ -64,7 +84,7 @@ reported about the loaded packages. See the documentation for type LoadMode
 for details.
 
 Most tools should pass their command-line arguments (after any flags)
-uninterpreted to the loader, so that the loader can interpret them
+uninterpreted to [Load], so that it can interpret them
 according to the conventions of the underlying build system.
 See the Example function for typical usage.
 */