x/tools/gopls: improve command-line help output

[cespare]

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, linked from the gopls user guide, could be fleshed out with a description of how to use the command-line interface. (Compare with the guru user manual.)

[jbszczepaniak]

I'll work on this one.

[jbszczepaniak]

@stamblerre Currently all of the commands are printed as a signle list:

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
  folding_ranges : display selected file's folding ranges
  format : format the code according to the go standard
  highlight : display selected identifier's highlights
  implementation : display selected identifier's implementation
  imports : updates import statements
  links : list links in a file
  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

What do you think about separating this into "main" (looking for better naming) commands and "features" that can be run adhoc like this:

Available commands are:
main:
  serve : run a server for Go code using the Language Server Protocol
  bug : report a bug in gopls
  version : print the gopls version information
features:
  check : show diagnostic results for the specified file
  folding_ranges : display selected file's folding ranges
  format : format the code according to the go standard
  highlight : display selected identifier's highlights
  implementation : display selected identifier's implementation
  imports : updates import statements
  links : list links in a file
  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

I think it shows intent of the commands more clearly.

[stamblerre]

@jbszczepaniak: That sounds reasonable to me!

[jbszczepaniak]

OK, one more question. Should running command without any flag nor command behave like this? I find it confusing:

➜  gopls git:(master) ✗ gopls

gopls: missing Content-Length header

If you'll not provide valid json rpc message it does nothing and when you hit enter you get missing content message. My proposition is to print help whenever you run just gopls and allow feeding stdin with json under additional command. What do you think?

[jbszczepaniak]

And one more again ;)
Following flags printed when doing gopls -h:

  -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
  -port int
    	port on which to run gopls for debugging purposes
  -rpc.trace
    	Print the full rpc trace in lsp inspector format

concern only gopls serve command. Shouldn't they be printed only with gopls serve -h? I don't think it makes sense to print them on gopls -h

[stamblerre]

@jbszczepaniak: Both of your comments sound good! We can also have more discussion once you send out a CL for review.

[jbszczepaniak]

@stamblerre could you tell me about this compatibility thing?
https://github.com/golang/tools/blob/master/internal/lsp/cmd/cmd.go#L117

// If no arguments are passed it will invoke the server sub command, as a
// temporary measure for compatibility.

It pops here as well https://github.com/golang/tools/blob/master/internal/lsp/cmd/cmd.go#L43:

// We include the server configuration directly for now, so the flags work
// even without the verb.
// TODO: Remove this when we stop allowing the serve verb by default.
Serve Serve

With this my proposal cannot be done and probably I am missing some context and discussion that took place some time ago.

[gopherbot]

Change https://golang.org/cl/210359 mentions this issue: internal/lsp: clean up command line of gopls

[jbszczepaniak]

I decided to submit first change for this issue to keep things small. Things I didn't do:

• update README
• improvment of usage of each subcommands
• removing serve as default command
• help is not an alias to --help

[alissonbrunosa]

I think we should closed this issue, since the PR has already been merged.

cc @stamblerre

[stamblerre]

Hm, actually I think there is still work to do here (see #35855 (comment)).

gopls help still prints Unknown command help and the list of flags is missing. Also, commands like gopls help rename should probably work.

Dealing with serve as the default command could probably be split out into a separate issue as there's more complexity to it (language clients would need to change how they start gopls).

[gopherbot]

Change https://golang.org/cl/330854 mentions this issue: internal/lsp/cmd: remove empty flag print

[gopherbot]

Change https://golang.org/cl/330949 mentions this issue: internal/lsp/cmd: help command is recognised

[cespare]

@stamblerre as far as I'm concerned, we can close this issue. I'll leave it open since you indicated that we should still add gopls help and gopls help rename but that's more like a small bonus feature whereas the original issue I filed was focused on several UX defects that have all been fixed now.