Repository: go
Issue: x/tools/gopls: improve command-line help output
Labels: gopls,Tools

I installed `golang.org/x/tools/gopls@latest` and tried to look at its command-line tool options (rename, etc).

First I tried `-h`, since this is a typical way to make Go tools show usage:

```
$ gopls -h
Usage of gopls:
  -debug string
        Serve debug information on the supplied address
  -listen string
        address on which to listen for remote connections
  -logfile string
        filename to log to. if value is "auto", then logging to a default output file is enabled
  -mode string
        no effect
  -ocagent string
        The address of the ocagent, or off (default "off")
  -port int
        port on which to run gopls for debugging purposes
  -profile.cpu string
        write CPU profile to this file
  -profile.mem string
        write memory profile to this file
  -profile.trace string
        write trace log to this file
  -remote string
        *EXPERIMENTAL* - forward all commands to a remote lsp
  -rpc.trace
        Print the full rpc trace in lsp inspector format
  -v    Verbose output
```

So this shows the flags (for which command?), but not the actual commands. Next I tried `gopls help`:

```
$ gopls help
gopls: Unknown command help
The Go Language source tools.

Usage: gopls [flags] <command> [command-flags] [command-args]

Available commands are:
  serve : run a server for Go code using the Language Server Protocol
  bug : report a bug in gopls
  check : show diagnostic results for the specified file
  format : format the code according to the go standard
  links : list links in a file
  imports : updates import statements
  query : answer queries about go source code
  references : display selected identifier's references
  rename : rename selected identifier
  signature : display selected identifier's signature
  fix : apply suggested fixes
  symbols : display selected file's symbols
  version : print the gopls version information

gopls flags are:
```

That works, but only accidentally ("Unknown command help"). Also note the trailing "gopls flags are:" followed by no flags.

Finally, I tried running `gopls rename -h` to see how one uses this tool:

```
$ gopls rename -h
Usage of rename:
  -d    display diffs instead of rewriting files
  -w    write result to (source) file instead of stdout
```

This does not provide enough information to actually use `gopls rename`.

We should improve this situation:

* `gopls -h` should print out the possible commands.
* After printing the commands, it should print the common flags (as well as some text explaining that these are flags that apply across all commands), and perhaps some text suggesting the user can run `gopls <command> -h` to find the flags for a particular command.
* Each command's `-h` output could say what the command actually does and how to use it, not just list the flags.

For bonus points:

* `gopls help` could be a synonym for `gopls -h/-help`, since that's a common paradigm for "sub-command"-style tools (see `go help` for example).
* The [command-line flags markdown page](https://github.com/golang/tools/blob/master/gopls/doc/command-line.md), linked from [the gopls user guide](https://github.com/golang/tools/blob/master/gopls/doc/user.md), could be fleshed out with a description of how to use the command-line interface. (Compare with the [guru user manual](http://golang.org/s/using-guru).)