gopls: cleanup the main help pages

This no longer has an invalid usage line, and mentions the help command.
It also mentions the no command form that is the same as serve.

For #41860

Change-Id: I9add50d295e1eb66152876617f27761a9441e67f
Reviewed-on: https://go-review.googlesource.com/c/tools/+/367842
Trust: Ian Cottrell <iancottrell@google.com>
Run-TryBot: Ian Cottrell <iancottrell@google.com>
Reviewed-by: Robert Findley <rfindley@google.com>
gopls-CI: kokoro <noreply+kokoro@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>

internal/lsp/cmd/cmd.go

@@ -105,11 +105,11 @@ func New(name, wd string, env []string, options func(*source.Options)) *Applicat
 func (app *Application) Name() string { return app.name }
 
 // Usage implements tool.Application returning empty extra argument usage.
-func (app *Application) Usage() string { return "<command> [command-flags] [command-args]" }
+func (app *Application) Usage() string { return "" }
 
 // ShortHelp implements tool.Application returning the main binary help.
 func (app *Application) ShortHelp() string {
-	return "The Go Language source tools."
+	return ""
 }
 
 // DetailedHelp implements tool.Application returning the main binary help.
@@ -119,11 +119,16 @@ func (app *Application) DetailedHelp(f *flag.FlagSet) {
 	defer w.Flush()
 
 	fmt.Fprint(w, `
-gopls is a Go language server. It is typically used with an editor to provide
-language features. When no command is specified, gopls will default to the 'serve'
-command. The language features can also be accessed via the gopls command-line interface.
+gopls is a Go language server.
 
-command:
+It is typically used with an editor to provide language features. When no
+command is specified, gopls will default to the 'serve' command. The language
+features can also be accessed via the gopls command-line interface.
+
+Usage:
+  gopls help [<subject>]
+
+Command:
 `)
 	fmt.Fprint(w, "\nMain\t\n")
 	for _, c := range app.mainCommands() {

internal/lsp/cmd/serve.go

@@ -48,7 +48,8 @@ func (s *Serve) ShortHelp() string {
 	return "run a server for Go code using the Language Server Protocol"
 }
 func (s *Serve) DetailedHelp(f *flag.FlagSet) {
-	fmt.Fprint(f.Output(), `
+	fmt.Fprint(f.Output(), `  gopls [flags] [server-flags]
+
 The server communicates using JSONRPC2 on stdin and stdout, and is intended to be run directly as
 a child of an editor process.
 

internal/lsp/cmd/subcommands.go

@@ -20,7 +20,7 @@ type subcommands []tool.Application
 func (s subcommands) DetailedHelp(f *flag.FlagSet) {
 	w := tabwriter.NewWriter(f.Output(), 0, 0, 2, ' ', 0)
 	defer w.Flush()
-	fmt.Fprint(w, "\nsubcommands:\n")
+	fmt.Fprint(w, "\nSubcommand:\n")
 	for _, c := range s {
 		fmt.Fprintf(w, "  %s\t%s\n", c.Name(), c.ShortHelp())
 	}

internal/lsp/cmd/usage/inspect.hlp

@@ -3,6 +3,6 @@ interact with the gopls daemon (deprecated: use 'remote')
 Usage:
   gopls [flags] inspect <subcommand> [arg]...
 
-subcommands:
+Subcommand:
   sessions  print information about current gopls sessions
   debug     start the debug server

internal/lsp/cmd/usage/remote.hlp

@@ -3,6 +3,6 @@ interact with the gopls daemon
 Usage:
   gopls [flags] remote <subcommand> [arg]...
 
-subcommands:
+Subcommand:
   sessions  print information about current gopls sessions
   debug     start the debug server

internal/lsp/cmd/usage/serve.hlp

@@ -2,6 +2,7 @@ run a server for Go code using the Language Server Protocol
 
 Usage:
   gopls [flags] serve [server-flags]
+  gopls [flags] [server-flags]
 
 The server communicates using JSONRPC2 on stdin and stdout, and is intended to be run directly as
 a child of an editor process.

internal/lsp/cmd/usage/usage.hlp

@@ -1,13 +1,14 @@
-The Go Language source tools.
+
+gopls is a Go language server.
+
+It is typically used with an editor to provide language features. When no
+command is specified, gopls will default to the 'serve' command. The language
+features can also be accessed via the gopls command-line interface.
 
 Usage:
-  gopls [flags] <command> [command-flags] [command-args]
+  gopls help [<subject>]
 
-gopls is a Go language server. It is typically used with an editor to provide
-language features. When no command is specified, gopls will default to the 'serve'
-command. The language features can also be accessed via the gopls command-line interface.
-
-command:
+Command:
 
 Main                
   serve             run a server for Go code using the Language Server Protocol

internal/lsp/cmd/usage/workspace.hlp

@@ -3,5 +3,5 @@ manage the gopls workspace (experimental: under development)
 Usage:
   gopls [flags] workspace <subcommand> [arg]...
 
-subcommands:
+Subcommand:
   generate  generate a gopls.mod file for a workspace

internal/tool/tool.go

@@ -103,16 +103,18 @@ func Main(ctx context.Context, app Application, args []string) {
 // error.
 func Run(ctx context.Context, s *flag.FlagSet, app Application, args []string) error {
 	s.Usage = func() {
-		fmt.Fprintf(s.Output(), "%s\n\nUsage:\n  ", app.ShortHelp())
-		if sub, ok := app.(SubCommand); ok && sub.Parent() != "" {
-			fmt.Fprintf(s.Output(), "%s [flags] %s", sub.Parent(), app.Name())
-		} else {
-			fmt.Fprintf(s.Output(), "%s [flags]", app.Name())
+		if app.ShortHelp() != "" {
+			fmt.Fprintf(s.Output(), "%s\n\nUsage:\n  ", app.ShortHelp())
+			if sub, ok := app.(SubCommand); ok && sub.Parent() != "" {
+				fmt.Fprintf(s.Output(), "%s [flags] %s", sub.Parent(), app.Name())
+			} else {
+				fmt.Fprintf(s.Output(), "%s [flags]", app.Name())
+			}
+			if usage := app.Usage(); usage != "" {
+				fmt.Fprintf(s.Output(), " %s", usage)
+			}
+			fmt.Fprint(s.Output(), "\n")
 		}
-		if usage := app.Usage(); usage != "" {
-			fmt.Fprintf(s.Output(), " %s", usage)
-		}
-		fmt.Fprint(s.Output(), "\n")
 		app.DetailedHelp(s)
 	}
 	p := addFlags(s, reflect.StructField{}, reflect.ValueOf(app))