Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/tools/gopls: improve help output #35855

Open
cespare opened this issue Nov 26, 2019 · 3 comments

Comments

@cespare
Copy link
Contributor

@cespare cespare commented Nov 26, 2019

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:

@gopherbot gopherbot added this to the Unreleased milestone Nov 26, 2019
@stamblerre stamblerre self-assigned this Nov 26, 2019
@stamblerre stamblerre removed their assignment Nov 30, 2019
@jbszczepaniak

This comment has been minimized.

Copy link

@jbszczepaniak jbszczepaniak commented Nov 30, 2019

I'll work on this one.

@stamblerre stamblerre modified the milestones: Unreleased, gopls v1.0 Dec 4, 2019
@jbszczepaniak

This comment has been minimized.

Copy link

@jbszczepaniak jbszczepaniak commented Dec 4, 2019

@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

This comment has been minimized.

Copy link
Contributor

@stamblerre stamblerre commented Dec 4, 2019

@jbszczepaniak: That sounds reasonable to me!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
4 participants
You can’t perform that action at this time.