README: restructure and update
Update the README file to remove stale information
and describe the most important packages and tools
in the repo, to help users find their bearings amid
the plethora of obscure or obsolete things.
Also, consolidate the Contributing information at the end.
Change-Id: I499c7c62bff142529063df0fc65d9b3da3978379
Reviewed-on: https://go-review.googlesource.com/c/tools/+/403676
Reviewed-by: Robert Findley <rfindley@google.com>
diff --git a/README.md b/README.md
index 71a945a..5cd8f0a 100644
--- a/README.md
+++ b/README.md
@@ -2,23 +2,90 @@
[](https://pkg.go.dev/golang.org/x/tools)
-This subrepository holds the source for various packages and tools that support
-the Go programming language.
+This repository provides the `golang.org/x/tools` module, comprising
+various tools and packages mostly for static analysis of Go programs,
+some of which are listed below.
+Use the "Go reference" link above for more information about any package.
-Some of the tools, `godoc` and `vet` for example, are included in binary Go
-distributions.
+It also contains the
+[`golang.org/x/tools/gopls`](https://pkg.go.dev/golang.org/x/tools/gopls)
+module, whose root package is a language-server protocol (LSP) server for Go.
+An LSP server analyses the source code of a project and
+responds to requests from a wide range of editors such as VSCode and
+Vim, allowing them to support IDE-like functionality.
-Others, including the Go `guru` and the test coverage tool, can be fetched with
-`go install`.
+<!-- List only packages of general interest below. -->
-Packages include a type-checker for Go and an implementation of the
-Static Single Assignment form (SSA) representation for Go programs.
+Selected commands:
-## Download/Install
+- `cmd/goimports` formats a Go program like `go fmt` and additionally
+ inserts import statements for any packages required by the file
+ after it is edited.
+- `cmd/callgraph` prints the call graph of a Go program.
+- `cmd/digraph` is a utility for manipulating directed graphs in textual notation.
+- `cmd/stringer` generates declarations (including a `String` method) for "enum" types.
+- `cmd/toolstash` is a utility to simplify working with multiple versions of the Go toolchain.
-The easiest way to install is to run `go install golang.org/x/tools/...@latest`.
+These commands may be fetched with a command such as
+`go install golang.org/x/tools/cmd/goimports@latest`.
-## JS/CSS Formatting
+Selected packages:
+
+- `go/ssa` provides a static single-assignment form (SSA) intermediate
+ representation (IR) for Go programs, similar to a typical compiler,
+ for use by analysis tools.
+
+- `go/packages` provides a simple interface for loading, parsing, and
+ type checking a complete Go program from source code.
+
+- `go/analysis` provides a framework for modular static analysis of Go
+ programs.
+
+- `go/callgraph` provides call graphs of Go programs using a variety
+ of algorithms with different trade-offs.
+
+- `go/ast/inspector` provides an optimized means of traversing a Go
+ parse tree for use in analysis tools.
+
+- `go/cfg` provides a simple control-flow graph (CFG) for a Go function.
+
+- `go/expect` reads Go source files used as test inputs and interprets
+ special comments within them as queries or assertions for testing.
+
+- `go/gcexportdata` and `go/gccgoexportdata` read and write the binary
+ files containing type information used by the standard and `gccgo` compilers.
+
+- `go/types/objectpath` provides a stable naming scheme for named
+ entities ("objects") in the `go/types` API.
+
+Numerous other packages provide more esoteric functionality.
+
+<!-- Some that didn't make the cut:
+
+golang.org/x/tools/benchmark/parse
+golang.org/x/tools/go/ast/astutil
+golang.org/x/tools/go/types/typeutil
+golang.org/x/tools/go/vcs
+golang.org/x/tools/godoc
+golang.org/x/tools/playground
+golang.org/x/tools/present
+golang.org/x/tools/refactor/importgraph
+golang.org/x/tools/refactor/rename
+golang.org/x/tools/refactor/satisfy
+golang.org/x/tools/txtar
+
+-->
+
+## Contributing
+
+This repository uses Gerrit for code changes.
+To learn how to submit changes, see https://golang.org/doc/contribute.html.
+
+The main issue tracker for the tools repository is located at
+https://github.com/golang/go/issues. Prefix your issue with "x/tools/(your
+subdir):" in the subject line, so it is easy to find.
+
+### JavaScript and CSS Formatting
This repository uses [prettier](https://prettier.io/) to format JS and CSS files.
@@ -26,12 +93,3 @@
It is encouraged that all JS and CSS code be run through this before submitting
a change. However, it is not a strict requirement enforced by CI.
-
-## Report Issues / Send Patches
-
-This repository uses Gerrit for code changes. To learn how to submit changes to
-this repository, see https://golang.org/doc/contribute.html.
-
-The main issue tracker for the tools repository is located at
-https://github.com/golang/go/issues. Prefix your issue with "x/tools/(your
-subdir):" in the subject line, so it is easy to find.
