gopls/internal/golang: support hover and definition operations over doc links

Now gopls has already support highlight doc links, and it would be
useful to support hover and defition over doc links.

Fixes golang/go#64648

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

Author: rogeryk

gopls/internal/golang/comment.go

@@ -5,12 +5,24 @@
 package golang
 
 import (
+	"context"
+	"errors"
 	"fmt"
+	"go/ast"
 	"go/doc/comment"
+	"go/token"
+	"go/types"
+	"strings"
 
+	"golang.org/x/tools/gopls/internal/cache"
+	"golang.org/x/tools/gopls/internal/cache/parsego"
+	"golang.org/x/tools/gopls/internal/protocol"
 	"golang.org/x/tools/gopls/internal/settings"
+	"golang.org/x/tools/gopls/internal/util/safetoken"
 )
 
+var errNoCommentReference = errors.New("no comment reference found")
+
 // CommentToMarkdown converts comment text to formatted markdown.
 // The comment was prepared by DocReader,
 // so it is known not to have leading, trailing blank lines
@@ -39,3 +51,127 @@ func CommentToMarkdown(text string, options *settings.Options) string {
 	easy := pr.Markdown(doc)
 	return string(easy)
 }
+
+// docLinkDefinition finds the definition of the doc link in comments at pos.
+// If there is no reference at pos, returns errNoCommentReference.
+func docLinkDefinition(ctx context.Context, snapshot *cache.Snapshot, pkg *cache.Package, pgf *parsego.File, pos token.Pos) ([]protocol.Location, error) {
+	obj, _, err := parseDocLink(pkg, pgf, pos)
+	if err != nil {
+		return nil, err
+	}
+	loc, err := mapPosition(ctx, pkg.FileSet(), snapshot, obj.Pos(), adjustedObjEnd(obj))
+	if err != nil {
+		return nil, err
+	}
+	return []protocol.Location{loc}, nil
+}
+
+// parseDocLink parses a doc link in a comment such as [fmt.Println]
+// and returns the symbol at pos, along with the link's start position.
+func parseDocLink(pkg *cache.Package, pgf *parsego.File, pos token.Pos) (types.Object, protocol.Range, error) {
+	var comment *ast.Comment
+	for _, cg := range pgf.File.Comments {
+		for _, c := range cg.List {
+			if c.Pos() <= pos && pos <= c.End() {
+				comment = c
+				break
+			}
+		}
+		if comment != nil {
+			break
+		}
+	}
+	if comment == nil {
+		return nil, protocol.Range{}, errNoCommentReference
+	}
+
+	// The canonical parsing algorithm is defined by go/doc/comment, but
+	// unfortunately its API provides no way to reliably reconstruct the
+	// position of each doc link from the parsed result.
+	line := safetoken.Line(pgf.Tok, pos)
+	var start, end token.Pos
+	if pgf.Tok.LineStart(line) > comment.Pos() {
+		start = pgf.Tok.LineStart(line)
+	} else {
+		start = comment.Pos()
+	}
+	if line < pgf.Tok.LineCount() && pgf.Tok.LineStart(line+1) < comment.End() {
+		end = pgf.Tok.LineStart(line + 1)
+	} else {
+		end = comment.End()
+	}
+
+	offsetStart, offsetEnd, err := safetoken.Offsets(pgf.Tok, start, end)
+	if err != nil {
+		return nil, protocol.Range{}, err
+	}
+
+	text := string(pgf.Src[offsetStart:offsetEnd])
+	lineOffset := int(pos - start)
+
+	for _, idx := range docLinkRegex.FindAllStringSubmatchIndex(text, -1) {
+		// The [idx[2], idx[3]) identifies the first submatch,
+		// which is the reference name in the doc link.
+		// e.g. The "[fmt.Println]" reference name is "fmt.Println".
+		if !(idx[2] <= lineOffset && lineOffset < idx[3]) {
+			continue
+		}
+		p := lineOffset - idx[2]
+		name := text[idx[2]:idx[3]]
+		i := strings.LastIndexByte(name, '.')
+		for i != -1 {
+			if p > i {
+				break
+			}
+			name = name[:i]
+			i = strings.LastIndexByte(name, '.')
+		}
+		obj := lookupObjectByName(pkg, pgf, name)
+		if obj == nil {
+			return nil, protocol.Range{}, errNoCommentReference
+		}
+		namePos := start + token.Pos(idx[2]+i+1)
+		rng, err := pgf.PosRange(namePos, namePos+token.Pos(len(obj.Name())))
+		if err != nil {
+			return nil, protocol.Range{}, err
+		}
+		return obj, rng, nil
+	}
+
+	return nil, protocol.Range{}, errNoCommentReference
+}
+
+func lookupObjectByName(pkg *cache.Package, pgf *parsego.File, name string) types.Object {
+	scope := pkg.Types().Scope()
+	fileScope := pkg.TypesInfo().Scopes[pgf.File]
+	pkgName, suffix, _ := strings.Cut(name, ".")
+	obj, ok := fileScope.Lookup(pkgName).(*types.PkgName)
+	if ok {
+		scope = obj.Imported().Scope()
+		if suffix == "" {
+			return obj
+		}
+		name = suffix
+	}
+
+	recv, method, ok := strings.Cut(name, ".")
+	if ok {
+		obj, ok := scope.Lookup(recv).(*types.TypeName)
+		if !ok {
+			return nil
+		}
+		t, ok := obj.Type().(*types.Named)
+		if !ok {
+			return nil
+		}
+		for i := 0; i < t.NumMethods(); i++ {
+			m := t.Method(i)
+			if m.Name() == method {
+				return m
+			}
+		}
+		return nil
+	}
+
+	return scope.Lookup(name)
+}

gopls/internal/golang/definition.go

@@ -66,13 +66,19 @@ func Definition(ctx context.Context, snapshot *cache.Snapshot, fh file.Handle, p
 	// Handle the case where the cursor is in a linkname directive.
 	locations, err := LinknameDefinition(ctx, snapshot, pgf.Mapper, position)
 	if !errors.Is(err, ErrNoLinkname) {
-		return locations, err
+		return locations, err // may be success or failure
 	}
 
 	// Handle the case where the cursor is in an embed directive.
 	locations, err = EmbedDefinition(pgf.Mapper, position)
 	if !errors.Is(err, ErrNoEmbed) {
-		return locations, err
+		return locations, err // may be success or failure
+	}
+
+	// Handle the case where the cursor is in a doc link.
+	locations, err = docLinkDefinition(ctx, snapshot, pkg, pgf, pos)
+	if !errors.Is(err, errNoCommentReference) {
+		return locations, err // may be success or failure
 	}
 
 	// The general case: the cursor is on an identifier.

gopls/internal/golang/hover.go

@@ -33,6 +33,7 @@ import (
 	"golang.org/x/tools/gopls/internal/file"
 	"golang.org/x/tools/gopls/internal/protocol"
 	"golang.org/x/tools/gopls/internal/settings"
+	gastutil "golang.org/x/tools/gopls/internal/util/astutil"
 	"golang.org/x/tools/gopls/internal/util/bug"
 	"golang.org/x/tools/gopls/internal/util/safetoken"
 	"golang.org/x/tools/gopls/internal/util/slices"
@@ -134,52 +135,77 @@ func hover(ctx context.Context, snapshot *cache.Snapshot, fh file.Handle, pp pro
 		return protocol.Range{}, nil, err
 	}
 
-	// Handle hovering over import paths, which do not have an associated
-	// identifier.
-	for _, spec := range pgf.File.Imports {
-		// We are inclusive of the end point here to allow hovering when the cursor
-		// is just after the import path.
-		if spec.Path.Pos() <= pos && pos <= spec.Path.End() {
-			return hoverImport(ctx, snapshot, pkg, pgf, spec)
-		}
-	}
-
 	// Handle hovering over the package name, which does not have an associated
 	// object.
 	// As with import paths, we allow hovering just after the package name.
-	if pgf.File.Name != nil && pgf.File.Name.Pos() <= pos && pos <= pgf.File.Name.Pos() {
+	if pgf.File.Name != nil && gastutil.NodeContains(pgf.File.Name, pos) {
 		return hoverPackageName(pkg, pgf)
 	}
 
-	// Handle hovering over (non-import-path) literals.
-	if path, _ := astutil.PathEnclosingInterval(pgf.File, pos, pos); len(path) > 0 {
-		if lit, _ := path[0].(*ast.BasicLit); lit != nil {
-			return hoverLit(pgf, lit, pos)
-		}
-	}
-
 	// Handle hovering over embed directive argument.
 	pattern, embedRng := parseEmbedDirective(pgf.Mapper, pp)
 	if pattern != "" {
 		return hoverEmbed(fh, embedRng, pattern)
 	}
 
+	// hoverRange is the range reported to the client (e.g. for highlighting).
+	// It may be an expansion around the selected identifier,
+	// for instance when hovering over a linkname directive or doc link.
+	var hoverRange *protocol.Range
 	// Handle linkname directive by overriding what to look for.
-	var linkedRange *protocol.Range // range referenced by linkname directive, or nil
 	if pkgPath, name, offset := parseLinkname(pgf.Mapper, pp); pkgPath != "" && name != "" {
 		// rng covering 2nd linkname argument: pkgPath.name.
 		rng, err := pgf.PosRange(pgf.Tok.Pos(offset), pgf.Tok.Pos(offset+len(pkgPath)+len(".")+len(name)))
 		if err != nil {
 			return protocol.Range{}, nil, fmt.Errorf("range over linkname arg: %w", err)
 		}
-		linkedRange = &rng
+		hoverRange = &rng
 
 		pkg, pgf, pos, err = findLinkname(ctx, snapshot, PackagePath(pkgPath), name)
 		if err != nil {
 			return protocol.Range{}, nil, fmt.Errorf("find linkname: %w", err)
 		}
 	}
 
+	// Handle hovering over a doc link
+	if obj, rng, _ := parseDocLink(pkg, pgf, pos); obj != nil {
+		hoverRange = &rng
+		// Handle builtins, which don't have a package or position.
+		if !obj.Pos().IsValid() {
+			h, err := hoverBuiltin(ctx, snapshot, obj)
+			return *hoverRange, h, err
+		}
+		objURI := safetoken.StartPosition(pkg.FileSet(), obj.Pos())
+		pkg, pgf, err = NarrowestPackageForFile(ctx, snapshot, protocol.URIFromPath(objURI.Filename))
+		if err != nil {
+			return protocol.Range{}, nil, err
+		}
+		pos = pgf.Tok.Pos(objURI.Offset)
+	}
+
+	// Handle hovering over import paths, which do not have an associated
+	// identifier.
+	for _, spec := range pgf.File.Imports {
+		if gastutil.NodeContains(spec, pos) {
+			rng, hoverJSON, err := hoverImport(ctx, snapshot, pkg, pgf, spec)
+			if err != nil {
+				return protocol.Range{}, nil, err
+			}
+			if hoverRange == nil {
+				hoverRange = &rng
+			}
+			return *hoverRange, hoverJSON, nil
+		}
+	}
+	// Handle hovering over (non-import-path) literals.
+	if path, _ := astutil.PathEnclosingInterval(pgf.File, pos, pos); len(path) > 0 {
+		if lit, _ := path[0].(*ast.BasicLit); lit != nil {
+			return hoverLit(pgf, lit, pos)
+		}
+	}
+
+	// Handle hover over identifier.
+
 	// The general case: compute hover information for the object referenced by
 	// the identifier at pos.
 	ident, obj, selectedType := referencedObject(pkg, pgf, pos)
@@ -188,14 +214,12 @@ func hover(ctx context.Context, snapshot *cache.Snapshot, fh file.Handle, pp pro
 	}
 
 	// Unless otherwise specified, rng covers the ident being hovered.
-	var rng protocol.Range
-	if linkedRange != nil {
-		rng = *linkedRange
-	} else {
-		rng, err = pgf.NodeRange(ident)
+	if hoverRange == nil {
+		rng, err := pgf.NodeRange(ident)
 		if err != nil {
 			return protocol.Range{}, nil, err
 		}
+		hoverRange = &rng
 	}
 
 	// By convention, we qualify hover information relative to the package
@@ -209,7 +233,7 @@ func hover(ctx context.Context, snapshot *cache.Snapshot, fh file.Handle, pp pro
 	if selectedType != nil {
 		fakeObj := types.NewVar(obj.Pos(), obj.Pkg(), obj.Name(), selectedType)
 		signature := types.ObjectString(fakeObj, qf)
-		return rng, &hoverJSON{
+		return *hoverRange, &hoverJSON{
 			Signature:  signature,
 			SingleLine: signature,
 			SymbolName: fakeObj.Name(),
@@ -219,7 +243,7 @@ func hover(ctx context.Context, snapshot *cache.Snapshot, fh file.Handle, pp pro
 	// Handle builtins, which don't have a package or position.
 	if !obj.Pos().IsValid() {
 		h, err := hoverBuiltin(ctx, snapshot, obj)
-		return rng, h, err
+		return *hoverRange, h, err
 	}
 
 	// For all other objects, consider the full syntax of their declaration in
@@ -523,7 +547,7 @@ func hover(ctx context.Context, snapshot *cache.Snapshot, fh file.Handle, pp pro
 		linkPath = strings.Replace(linkPath, mod.Path, mod.Path+"@"+mod.Version, 1)
 	}
 
-	return rng, &hoverJSON{
+	return *hoverRange, &hoverJSON{
 		Synopsis:          doc.Synopsis(docText),
 		FullDocumentation: docText,
 		SingleLine:        singleLineSignature,

gopls/internal/test/marker/testdata/definition/comment.txt

@@ -0,0 +1,21 @@
+This test executes definition requests over doc links.
+
+-- go.mod --
+module mod.com
+
+go 1.21
+
+-- a.go --
+package p
+
+import "strconv" //@loc(strconv, `"strconv"`)
+
+const NumberBase = 10 //@loc(NumberBase, "NumberBase")
+
+// [Conv] converts s to an int. //@def("Conv", Conv)
+func Conv(s string) int { //@loc(Conv, "Conv")
+	// [strconv.ParseInt] parses s and returns the integer corresponding to it. //@def("strconv", strconv)
+	// [NumberBase] is the base to use for number parsing. //@def("NumberBase", NumberBase)
+	i, _ := strconv.ParseInt(s, NumberBase, 64)
+	return int(i)
+}