gopls/internal/lsp/source: add documentation links to hover

Point to the documentation for entries like [fmt.Printf] in the
doc comments shown in hover. The links are to https://pkg.go.dev.

Fixes golang/go#58352

Change-Id: Ia5c8fb0e7eaa7861eac359fa138aa6d8d8ff1327
Reviewed-on: https://go-review.googlesource.com/c/tools/+/469715
Run-TryBot: Peter Weinberger <[email protected]>
TryBot-Result: Gopher Robot <[email protected]>
Reviewed-by: Robert Findley <[email protected]>

Author: pjweinbgo

gopls/internal/lsp/completion.go

@@ -104,7 +104,7 @@ func toProtocolCompletionItems(candidates []completion.CompletionItem, rng proto
 		doc := &protocol.Or_CompletionItem_documentation{
 			Value: protocol.MarkupContent{
 				Kind:  protocol.Markdown,
-				Value: source.CommentToMarkdown(candidate.Documentation),
+				Value: source.CommentToMarkdown(candidate.Documentation, options),
 			},
 		}
 		if options.PreferredContentFormat != protocol.Markdown {

gopls/internal/lsp/source/comment.go

@@ -29,7 +29,7 @@ import (
 // prefix removed unless empty, in which case it will be converted to a newline.
 //
 // URLs in the comment text are converted into links.
-func CommentToMarkdown(text string) string {
+func CommentToMarkdown(text string, _ *Options) string {
 	buf := &bytes.Buffer{}
 	commentToMarkdown(buf, text)
 	return buf.String()

gopls/internal/lsp/source/comment_go118_test.go

@@ -364,7 +364,7 @@ F declaration\.
 		tt.in = strings.TrimPrefix(tt.in, "\n")
 		tt.out = strings.TrimPrefix(tt.out, "\n")
 
-		if out := CommentToMarkdown(tt.in); out != tt.out {
+		if out := CommentToMarkdown(tt.in, nil); out != tt.out {
 			t.Errorf("#%d: mismatch\nhave: %q\nwant: %q", i, out, tt.out)
 		}
 	}

gopls/internal/lsp/source/comment_go118.go renamed to gopls/internal/lsp/source/comment_go119.go

@@ -21,14 +21,17 @@ package source
 // be replaced by this file, the golden test files should be updated.
 // (and checkSameMarkdown() could be replaced by a simple comparison.)
 
-import "go/doc/comment"
+import (
+	"fmt"
+	"go/doc/comment"
+)
 
 // CommentToMarkdown converts comment text to formatted markdown.
 // The comment was prepared by DocReader,
 // so it is known not to have leading, trailing blank lines
 // nor to have trailing spaces at the end of lines.
 // The comment markers have already been removed.
-func CommentToMarkdown(text string) string {
+func CommentToMarkdown(text string, options *Options) string {
 	var p comment.Parser
 	doc := p.Parse(text)
 	var pr comment.Printer
@@ -37,6 +40,17 @@ func CommentToMarkdown(text string) string {
 	// The godoc for comment.Printer says the tags
 	// avoid a security problem.
 	pr.HeadingID = func(*comment.Heading) string { return "" }
+	pr.DocLinkURL = func(link *comment.DocLink) string {
+		msg := fmt.Sprintf("https://%s/%s", options.LinkTarget, link.ImportPath)
+		if link.Name != "" {
+			msg += "#"
+			if link.Recv != "" {
+				msg += link.Recv + "."
+			}
+			msg += link.Name
+		}
+		return msg
+	}
 	easy := pr.Markdown(doc)
 	return string(easy)
 }

gopls/internal/lsp/source/hover.go

@@ -808,7 +808,7 @@ func formatDoc(h *HoverJSON, options *Options) string {
 		doc = h.FullDocumentation
 	}
 	if options.PreferredContentFormat == protocol.Markdown {
-		return CommentToMarkdown(doc)
+		return CommentToMarkdown(doc, options)
 	}
 	return doc
 }

gopls/internal/lsp/source/signature_help.go

@@ -170,7 +170,7 @@ func stringToSigInfoDocumentation(s string, options *Options) *protocol.Or_Signa
 	v := s
 	k := protocol.PlainText
 	if options.PreferredContentFormat == protocol.Markdown {
-		v = CommentToMarkdown(s)
+		v = CommentToMarkdown(s, options)
 		// whether or not content is newline terminated may not matter for LSP clients,
 		// but our tests expect trailing newlines to be stripped.
 		v = strings.TrimSuffix(v, "\n") // TODO(pjw): change the golden files

gopls/internal/regtest/misc/hover_test.go

@@ -343,3 +343,42 @@ func Hello() string {
 		}
 	})
 }
+
+// Test that the generated markdown contains links for Go references.
+// https://github.com/golang/go/issues/58352
+func TestHoverLinks(t *testing.T) {
+	testenv.NeedsGo1Point(t, 19)
+	const input = `
+-- go.mod --
+go 1.19
+module mod.com
+-- main.go --
+package main
+// [fmt]
+var A int
+// [fmt.Println]
+var B int
+// [golang.org/x/tools/go/packages.Package.String]
+var C int
+`
+	var tests = []struct {
+		pat string
+		ans string
+	}{
+		{"A", "fmt"},
+		{"B", "fmt#Println"},
+		{"C", "golang.org/x/tools/go/packages#Package.String"},
+	}
+	for _, test := range tests {
+		Run(t, input, func(t *testing.T, env *Env) {
+			env.OpenFile("main.go")
+			loc := env.RegexpSearch("main.go", test.pat)
+			hover, _ := env.Hover(loc)
+			hoverContent := hover.Value
+			want := fmt.Sprintf("%s/%s", "https://pkg.go.dev", test.ans)
+			if !strings.Contains(hoverContent, want) {
+				t.Errorf("hover:%q does not contain link %q", hoverContent, want)
+			}
+		})
+	}
+}