gopls/internal/golang: RenderPackageDoc: fix doc links

Previously, a variety of links generated by the go/doc/comment
package were not valid. This CL configures the parser and printer
hooks to query the cache.Package representation, and now
generates valid crosslinks for all references.

Tested interactively on a wide variety of cross links.

Change-Id: Iaf1fffe52ea96e3be5df78227cf8395006caa59a
Reviewed-on: https://go-review.googlesource.com/c/tools/+/575377
Auto-Submit: Alan Donovan <[email protected]>
Reviewed-by: Robert Findley <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>

Author: adonovan

gopls/internal/golang/pkgdoc.go

@@ -22,6 +22,9 @@ package golang
 // - add push notifications such as didChange -> reload.
 // - there appears to be a maximum file size beyond which the
 //   "source.doc" code action is not offered. Remove that.
+// - modify JS httpGET function to give a transient visual indication
+//   when clicking a source link that the editor is being navigated
+//   (in case it doesn't raise itself, like VS Code).
 
 import (
 	"bytes"
@@ -33,6 +36,7 @@ import (
 	"go/token"
 	"go/types"
 	"html"
+	"log"
 	"path/filepath"
 
 	"golang.org/x/tools/gopls/internal/cache"
@@ -41,6 +45,7 @@ import (
 	"golang.org/x/tools/gopls/internal/util/bug"
 	"golang.org/x/tools/gopls/internal/util/safetoken"
 	"golang.org/x/tools/gopls/internal/util/slices"
+	"golang.org/x/tools/gopls/internal/util/typesutil"
 	"golang.org/x/tools/internal/typesinternal"
 )
 
@@ -108,13 +113,72 @@ func RenderPackageDoc(pkg *cache.Package, posURL func(filename string, line, col
 		})
 	}
 
-	// Ensure doc links (e.g. "[fmt.Println]") become valid links.
-	docpkg.Printer().DocLinkURL = func(link *comment.DocLink) string {
-		fragment := link.Name
-		if link.Recv == "" {
-			fragment = link.Recv + "." + link.Name
+	var docHTML func(comment string) []byte
+	{
+		// Adapt doc comment parser and printer
+		// to our representation of Go packages
+		// so that doc links (e.g. "[fmt.Println]")
+		// become valid links.
+
+		printer := docpkg.Printer()
+		printer.DocLinkURL = func(link *comment.DocLink) string {
+			path := pkg.Metadata().PkgPath
+			if link.ImportPath != "" {
+				path = PackagePath(link.ImportPath)
+			}
+			fragment := link.Name
+			if link.Recv != "" {
+				fragment = link.Recv + "." + link.Name
+			}
+			return pkgURL(path, fragment)
+		}
+		parser := docpkg.Parser()
+		parser.LookupPackage = func(name string) (importPath string, ok bool) {
+			// Ambiguous: different files in the same
+			// package may have different import mappings,
+			// but the hook doesn't provide the file context.
+			// TODO(adonovan): conspire with docHTML to
+			// pass the doc comment's enclosing file through
+			// a shared variable, so that we can compute
+			// the correct per-file mapping.
+			//
+			// TODO(adonovan): check for PkgName.Name
+			// matches, but also check for
+			// PkgName.Imported.Namer matches, since some
+			// packages are typically imported under a
+			// non-default name (e.g. pathpkg "path") but
+			// may be referred to in doc links using their
+			// canonical name.
+			for _, f := range pkg.Syntax() {
+				for _, imp := range f.Imports {
+					pkgName, ok := typesutil.ImportedPkgName(pkg.TypesInfo(), imp)
+					if ok && pkgName.Name() == name {
+						return pkgName.Imported().Path(), true
+					}
+				}
+			}
+			return "", false
+		}
+		parser.LookupSym = func(recv, name string) (ok bool) {
+			defer func() {
+				log.Printf("LookupSym %q %q = %t ", recv, name, ok)
+			}()
+			// package-level decl?
+			if recv == "" {
+				return pkg.Types().Scope().Lookup(name) != nil
+			}
+
+			// method?
+			tname, ok := pkg.Types().Scope().Lookup(recv).(*types.TypeName)
+			if !ok {
+				return false
+			}
+			m, _, _ := types.LookupFieldOrMethod(tname.Type(), true, pkg.Types(), name)
+			return is[*types.Func](m)
+		}
+		docHTML = func(comment string) []byte {
+			return printer.HTML(parser.Parse(comment))
 		}
-		return pkgURL(PackagePath(link.ImportPath), fragment)
 	}
 
 	var buf bytes.Buffer
@@ -302,7 +366,7 @@ function httpGET(url) {
 		"https://pkg.go.dev/"+string(pkg.Types().Path()))
 
 	// package doc
-	fmt.Fprintf(&buf, "<div class='comment'>%s</div>\n", docpkg.HTML(docpkg.Doc))
+	fmt.Fprintf(&buf, "<div class='comment'>%s</div>\n", docHTML(docpkg.Doc))
 
 	// symbol index
 	fmt.Fprintf(&buf, "<h2>Index</h2>\n")
@@ -366,7 +430,7 @@ function httpGET(url) {
 			fmt.Fprintf(&buf, "<pre class='code'>%s</pre>\n", nodeHTML(&decl2))
 
 			// comment (if any)
-			fmt.Fprintf(&buf, "<div class='comment'>%s</div>\n", docpkg.HTML(v.Doc))
+			fmt.Fprintf(&buf, "<div class='comment'>%s</div>\n", docHTML(v.Doc))
 		}
 	}
 	fmt.Fprintf(&buf, "<h2 id='hdr-Constants'>Constants</h2>\n")
@@ -397,7 +461,7 @@ function httpGET(url) {
 				nodeHTML(docfn.Decl.Type))
 
 			// comment (if any)
-			fmt.Fprintf(&buf, "<div class='comment'>%s</div>\n", docpkg.HTML(docfn.Doc))
+			fmt.Fprintf(&buf, "<div class='comment'>%s</div>\n", docHTML(docfn.Doc))
 		}
 	}
 	funcs(docpkg.Funcs)
@@ -417,7 +481,7 @@ function httpGET(url) {
 		fmt.Fprintf(&buf, "<pre class='code'>%s</pre>\n", nodeHTML(&decl2))
 
 		// comment (if any)
-		fmt.Fprintf(&buf, "<div class='comment'>%s</div>\n", docpkg.HTML(doctype.Doc))
+		fmt.Fprintf(&buf, "<div class='comment'>%s</div>\n", docHTML(doctype.Doc))
 
 		// subelements
 		values(doctype.Consts) // constants of type T
@@ -437,7 +501,7 @@ function httpGET(url) {
 
 			// comment (if any)
 			fmt.Fprintf(&buf, "<div class='comment'>%s</div>\n",
-				docpkg.HTML(docmethod.Doc))
+				docHTML(docmethod.Doc))
 		}
 	}