[tools] go/packages: improve docs of 'go list' and GOPACKAGESDRIVER

[Gopher Robot (Gerrit)]

Gopher Robot submitted this change.

View Change

3 is the latest approved patch-set.
The change was submitted with unreviewed changes in the following files:

```
The name of the file: go/packages/doc.go
Insertions: 3, Deletions: 3.

@@ -25,10 +25,10 @@
 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
+(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.)
+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
```

Approvals: Go LUCI: TryBots succeeded Alan Donovan: Automatically submit change Michael Matloob: Looks good to me, approved

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 <golang...@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Michael Matloob <mat...@golang.org>
Auto-Submit: Alan Donovan <adon...@google.com>
---
M go/packages/doc.go
1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/go/packages/doc.go b/go/packages/doc.go
index a7a8f73..b2a0b7c 100644
--- a/go/packages/doc.go
+++ b/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.
+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,
-but all patterns with the prefix "query=", where query is a
+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 @@
 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.
 */

To view, visit change 547977. To unsubscribe, or for help writing mail filters, visit settings.

Gerrit-MessageType: merged

Gerrit-Project: tools

Gerrit-Branch: master

Gerrit-Change-Id: I3b41660c12942fdb15b8ea6f1f3c0b77ae91b897

Gerrit-Change-Number: 547977

Gerrit-PatchSet: 5

Gerrit-Owner: Alan Donovan <adon...@google.com>

Gerrit-Reviewer: Alan Donovan <adon...@google.com>

Gerrit-Reviewer: Go LUCI <golang...@luci-project-accounts.iam.gserviceaccount.com>

Gerrit-Reviewer: Gopher Robot <go...@golang.org>

Gerrit-Reviewer: Michael Matloob <mat...@golang.org>