_content: add more documentation for 'go tool' features in ref/mod

This CL addresses the issues in #71663 that appear in go.dev/ref/mod.

For golang/go#71663

Change-Id: I44d801b9e0e658547faf5ea3023f4a246a6a6964
Reviewed-on: https://go-review.googlesource.com/c/website/+/761040
Reviewed-by: Michael Matloob <matloob@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Auto-Submit: Michael Matloob <matloob@golang.org>

1 files changed, 34 insertions, 7 deletions

diff --git a/_content/ref/mod.md b/_content/ref/mod.md
index 702f18a8..d62d34cb 100644
--- a/_content/ref/mod.md
+++ b/_content/ref/mod.md
@@ -724,7 +724,7 @@ require (
 
 ### `tool` directive {#go-mod-file-tool}
 
-A `tool` directive adds a package as a dependency of the current module. It also
+Since Go 1.24, a `tool` directive adds a package as a dependency of the current module. It also
 makes it available to run with `go tool` when the current working directory is
 within this module, or within a workspace that contains this module.
 
@@ -1702,7 +1702,7 @@ zip files](#zip-files) (but see known bugs
 Usage:
 
 ```
-go get [-d] [-t] [-u] [build flags] [packages]
+go get [-d] [-t] [-u] [-tool] [build flags] [packages]
 ```
 
 Examples:
@@ -1829,6 +1829,8 @@ the `GOBIN` environment variable, which defaults to `$GOPATH/bin` or
   insecure schemes such as HTTP. The `GOINSECURE` [environment
   variable](#environment-variables) provides more fine-grained control and
   should be used instead.
+* The `-tool` flag instructs go to add a matching tool line to `go.mod` for each
+  listed package. If `-tool` is used with `@none`, the line will be removed.
 
 Since Go 1.16, [`go install`](#go-install) is the recommended command for
 building and installing programs. When used with a version suffix (like
@@ -1837,7 +1839,7 @@ ignoring the `go.mod` file in the current directory or any parent directory,
 if there is one.
 
 `go get` is more focused on managing requirements in `go.mod`. The `-d` flag
-is deprecated, and in Go 1.18, it will always be enabled.
+is deprecated, and since Go 1.18, it is always enabled.
 
 ### `go install` {#go-install}
 
@@ -1877,12 +1879,14 @@ Since Go 1.16, if the arguments have version suffixes (like `@latest` or
 one. This is useful for installing executables without affecting the
 dependencies of the main module.
 
-To eliminate ambiguity about which module versions are used in the build, the
-arguments must satisfy the following constraints:
+To eliminate ambiguity about which module versions are used in the build, if any
+of the arguments have version suffixes, the arguments must satisfy the following
+constraints:
 
 * Arguments must be package paths or package patterns (with "`...`" wildcards).
   They must not be standard packages (like `fmt`), meta-patterns (`std`, `cmd`,
-  `all`, `work`, `tool`), or relative or absolute file paths.
+  `all`, `work`, `tool`), or relative or absolute file paths. Note that `go install tool`
+  can be used without a version suffix: see below.
 * All arguments must have the same version suffix. Different queries are not
   allowed, even if they refer to the same version.
 * All arguments must refer to packages in the same module at the same version.
@@ -1905,7 +1909,30 @@ module-aware mode or `GOPATH` mode, depending on the `GO111MODULE` environment
 variable and the presence of a `go.mod` file. See [Module-aware
 commands](#mod-commands) for details. If module-aware mode is enabled, `go
 install` runs in the context of the main module, which may be different from the
-module containing the package being installed.
+module containing the package being installed. In module-aware mode,
+`go install tool` can be used from a module to install all the tools in the module.
+
+### `go tool` {#go-tool}
+
+Usage:
+
+```
+go tool [-n] command [args...]
+```
+
+Example:
+
+```
+$ go tool golang.org/x/tools/cmd/stringer
+$ go tool stringer
+```
+
+In module mode, the `go tool` command can be used to build and run tools
+declared in `go.mod` files using a [`tool` directive](#go-mod-file-tool).
+The command can be specified using the full package path to a tool declared using
+a tool directive. The default binary name of the tool, which is the last component of
+the package path, excluding the major version suffix, can also be used if it is unique
+among installed tools.
 
 ### `go list -m` {#go-list-m}