tools/gopls: add cmd support for signature

This change adds command line support for signatureHelp.
If the location provided corresponds to a function, that
function signature is displayed. In case that function is
documented the related comment is shown as well.

Example:

$ gopls signature ~/tmp/foo/main.go:7:5
$
$ Next(n int) []byte
$
$ Next returns a slice containing the next n bytes from
$ the buffer, advancing the buffer as if the bytes had been
$ returned by Read.

Note that linebreaks shown in the comment are just to adhere
commit message guidelines. The command prints documentation
comments on one line.

Updates golang/go#32875

Change-Id: Ib0dcc3267c594f95d80b74f289c1235c2c0c5f64
Reviewed-on: https://go-review.googlesource.com/c/tools/+/204057
Reviewed-by: Rebecca Stambler <rstambler@golang.org>
Run-TryBot: Rebecca Stambler <rstambler@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>

internal/lsp/cmd/cmd.go

@@ -147,6 +147,7 @@ func (app *Application) commands() []tool.Application {
 		&query{app: app},
 		&references{app: app},
 		&rename{app: app},
+		&signature{app: app},
 		&suggestedfix{app: app},
 		&version{app: app},
 	}

internal/lsp/cmd/signature.go

@@ -0,0 +1,88 @@
+// Copyright 2019 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package cmd
+
+import (
+	"context"
+	"flag"
+	"fmt"
+
+	"golang.org/x/tools/internal/lsp/protocol"
+	"golang.org/x/tools/internal/span"
+	"golang.org/x/tools/internal/tool"
+)
+
+// signature implements the signature verb for gopls
+type signature struct {
+	app *Application
+}
+
+func (r *signature) Name() string      { return "signature" }
+func (r *signature) Usage() string     { return "<position>" }
+func (r *signature) ShortHelp() string { return "display selected identifier's signature" }
+func (r *signature) DetailedHelp(f *flag.FlagSet) {
+	fmt.Fprint(f.Output(), `
+Example:
+
+  $ # 1-indexed location (:line:column or :#offset) of the target identifier
+  $ gopls signature helper/helper.go:8:6
+  $ gopls signature helper/helper.go:#53
+
+  gopls signature flags are:
+`)
+	f.PrintDefaults()
+}
+
+func (r *signature) Run(ctx context.Context, args ...string) error {
+	if len(args) != 1 {
+		return tool.CommandLineErrorf("signature expects 1 argument (position)")
+	}
+
+	conn, err := r.app.connect(ctx)
+	if err != nil {
+		return err
+	}
+	defer conn.terminate(ctx)
+
+	from := span.Parse(args[0])
+	file := conn.AddFile(ctx, from.URI())
+	if file.err != nil {
+		return file.err
+	}
+
+	loc, err := file.mapper.Location(from)
+	if err != nil {
+		return err
+	}
+
+	tdpp := protocol.TextDocumentPositionParams{
+		TextDocument: protocol.TextDocumentIdentifier{
+			URI: protocol.NewURI(from.URI()),
+		},
+		Position: loc.Range.Start,
+	}
+	p := protocol.SignatureHelpParams{
+		TextDocumentPositionParams: tdpp,
+	}
+
+	s, err := conn.SignatureHelp(ctx, &p)
+	if err != nil {
+		return err
+	}
+
+	if len(s.Signatures) == 0 {
+		return tool.CommandLineErrorf("%v: not a function", from)
+	}
+
+	// there is only ever one possible signature,
+	// see toProtocolSignatureHelp in lsp/signature_help.go
+	signature := s.Signatures[0]
+	fmt.Printf("%s\n", signature.Label)
+	if signature.Documentation != "" {
+		fmt.Printf("\n%s\n", signature.Documentation)
+	}
+
+	return nil
+}

internal/lsp/cmd/test/cmdtest.go

@@ -82,10 +82,6 @@ func (r *runner) Symbol(t *testing.T, uri span.URI, expectedSymbols []protocol.D
 	//TODO: add command line symbol tests when it works
 }
 
-func (r *runner) SignatureHelp(t *testing.T, spn span.Span, expectedSignature *source.SignatureInformation) {
-	//TODO: add command line signature tests when it works
-}
-
 func (r *runner) Link(t *testing.T, uri span.URI, wantLinks []tests.Link) {
 	//TODO: add command line link tests when it works
 }

internal/lsp/cmd/test/signature.go

@@ -0,0 +1,39 @@
+// Copyright 2019 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package cmdtest
+
+import (
+	"fmt"
+	"testing"
+
+	"golang.org/x/tools/internal/lsp/cmd"
+	"golang.org/x/tools/internal/lsp/source"
+	"golang.org/x/tools/internal/tool"
+
+	"golang.org/x/tools/internal/span"
+)
+
+func (r *runner) SignatureHelp(t *testing.T, spn span.Span, expectedSignature *source.SignatureInformation) {
+	goldenTag := "-signature"
+	if expectedSignature != nil {
+		goldenTag = expectedSignature.Label + goldenTag
+	}
+	uri := spn.URI()
+	filename := uri.Filename()
+	target := filename + fmt.Sprintf(":%v:%v", spn.Start().Line(), spn.Start().Column())
+
+	app := cmd.New("gopls-test", r.data.Config.Dir, r.data.Config.Env, r.options)
+	got := CaptureStdOut(t, func() {
+		tool.Run(r.ctx, app, append([]string{"-remote=internal", "signature"}, target))
+	})
+
+	expect := string(r.data.Golden(goldenTag, filename, func() ([]byte, error) {
+		return []byte(got), nil
+	}))
+
+	if expect != got {
+		t.Errorf("signature failed failed for %s expected:\n%s\ngot:\n%s", filename, expect, got)
+	}
+}

internal/lsp/testdata/signature/signature.go.golden

@@ -0,0 +1,40 @@
+-- -signature --
+
+-- Bar(float64, ...byte)-signature --
+Bar(float64, ...byte)
+
+-- Foo(a string, b int) (c bool)-signature --
+Foo(a string, b int) (c bool)
+
+-- Next(n int) []byte-signature --
+Next(n int) []byte
+
+Next returns a slice containing the next n bytes from the buffer, advancing the buffer as if the bytes had been returned by Read.
+
+-- fn(hi string, there string) func(i int) rune-signature --
+fn(hi string, there string) func(i int) rune
+
+-- foo(e *json.Decoder) (*big.Int, error)-signature --
+foo(e *json.Decoder) (*big.Int, error)
+
+-- func(hi string, there string) func(i int) rune-signature --
+func(hi string, there string) func(i int) rune
+
+-- func(i int) rune-signature --
+func(i int) rune
+
+-- func(string, int) bool-signature --
+func(string, int) bool
+
+-- make(t Type, size ...int) Type-signature --
+make(t Type, size ...int) Type
+
+-- myFunc(foo int) string-signature --
+myFunc(foo int) string
+
+-- panic(v interface{})-signature --
+panic(v interface{})
+
+-- println(args ...Type)-signature --
+println(args ...Type)
+