| // 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 source |
| |
| import ( |
| "context" |
| "encoding/json" |
| "errors" |
| "fmt" |
| "go/ast" |
| "go/constant" |
| "go/doc" |
| "go/format" |
| "go/token" |
| "go/types" |
| "strconv" |
| "strings" |
| "time" |
| "unicode/utf8" |
| |
| "golang.org/x/text/unicode/runenames" |
| "golang.org/x/tools/internal/event" |
| "golang.org/x/tools/internal/lsp/bug" |
| "golang.org/x/tools/internal/lsp/protocol" |
| "golang.org/x/tools/internal/lsp/safetoken" |
| "golang.org/x/tools/internal/typeparams" |
| ) |
| |
| // HoverContext contains context extracted from the syntax and type information |
| // of a given node, for use in various summaries (hover, autocomplete, |
| // signature help). |
| type HoverContext struct { |
| // signatureSource is the object or node use to derive the hover signature. |
| // |
| // It may also hold a precomputed string. |
| // TODO(rfindley): pre-compute all signatures to avoid this indirection. |
| signatureSource interface{} |
| |
| // comment is the most relevant comment group associated with the hovered object. |
| Comment *ast.CommentGroup |
| } |
| |
| // HoverJSON contains information used by hover. It is also the JSON returned |
| // for the "structured" hover format |
| type HoverJSON struct { |
| // Synopsis is a single sentence synopsis of the symbol's documentation. |
| Synopsis string `json:"synopsis"` |
| |
| // FullDocumentation is the symbol's full documentation. |
| FullDocumentation string `json:"fullDocumentation"` |
| |
| // Signature is the symbol's signature. |
| Signature string `json:"signature"` |
| |
| // SingleLine is a single line describing the symbol. |
| // This is recommended only for use in clients that show a single line for hover. |
| SingleLine string `json:"singleLine"` |
| |
| // SymbolName is the types.Object.Name for the given symbol. |
| SymbolName string `json:"symbolName"` |
| |
| // LinkPath is the pkg.go.dev link for the given symbol. |
| // For example, the "go/ast" part of "pkg.go.dev/go/ast#Node". |
| LinkPath string `json:"linkPath"` |
| |
| // LinkAnchor is the pkg.go.dev link anchor for the given symbol. |
| // For example, the "Node" part of "pkg.go.dev/go/ast#Node". |
| LinkAnchor string `json:"linkAnchor"` |
| } |
| |
| func Hover(ctx context.Context, snapshot Snapshot, fh FileHandle, position protocol.Position) (*protocol.Hover, error) { |
| ident, err := Identifier(ctx, snapshot, fh, position) |
| if err != nil { |
| if hover, innerErr := hoverRune(ctx, snapshot, fh, position); innerErr == nil { |
| return hover, nil |
| } |
| return nil, nil |
| } |
| h, err := HoverIdentifier(ctx, ident) |
| if err != nil { |
| return nil, err |
| } |
| rng, err := ident.Range() |
| if err != nil { |
| return nil, err |
| } |
| hover, err := FormatHover(h, snapshot.View().Options()) |
| if err != nil { |
| return nil, err |
| } |
| return &protocol.Hover{ |
| Contents: protocol.MarkupContent{ |
| Kind: snapshot.View().Options().PreferredContentFormat, |
| Value: hover, |
| }, |
| Range: rng, |
| }, nil |
| } |
| |
| func hoverRune(ctx context.Context, snapshot Snapshot, fh FileHandle, position protocol.Position) (*protocol.Hover, error) { |
| ctx, done := event.Start(ctx, "source.hoverRune") |
| defer done() |
| |
| r, mrng, err := findRune(ctx, snapshot, fh, position) |
| if err != nil { |
| return nil, err |
| } |
| rng, err := mrng.Range() |
| if err != nil { |
| return nil, err |
| } |
| |
| var desc string |
| runeName := runenames.Name(r) |
| if len(runeName) > 0 && runeName[0] == '<' { |
| // Check if the rune looks like an HTML tag. If so, trim the surrounding <> |
| // characters to work around https://github.com/microsoft/vscode/issues/124042. |
| runeName = strings.TrimRight(runeName[1:], ">") |
| } |
| if strconv.IsPrint(r) { |
| desc = fmt.Sprintf("'%s', U+%04X, %s", string(r), uint32(r), runeName) |
| } else { |
| desc = fmt.Sprintf("U+%04X, %s", uint32(r), runeName) |
| } |
| return &protocol.Hover{ |
| Contents: protocol.MarkupContent{ |
| Kind: snapshot.View().Options().PreferredContentFormat, |
| Value: desc, |
| }, |
| Range: rng, |
| }, nil |
| } |
| |
| // ErrNoRuneFound is the error returned when no rune is found at a particular position. |
| var ErrNoRuneFound = errors.New("no rune found") |
| |
| // findRune returns rune information for a position in a file. |
| func findRune(ctx context.Context, snapshot Snapshot, fh FileHandle, position protocol.Position) (rune, MappedRange, error) { |
| pkg, pgf, err := GetParsedFile(ctx, snapshot, fh, NarrowestPackage) |
| if err != nil { |
| return 0, MappedRange{}, err |
| } |
| pos, err := pgf.Mapper.Pos(position) |
| if err != nil { |
| return 0, MappedRange{}, err |
| } |
| |
| // Find the basic literal enclosing the given position, if there is one. |
| var lit *ast.BasicLit |
| var found bool |
| ast.Inspect(pgf.File, func(n ast.Node) bool { |
| if found { |
| return false |
| } |
| if n, ok := n.(*ast.BasicLit); ok && pos >= n.Pos() && pos <= n.End() { |
| lit = n |
| found = true |
| } |
| return !found |
| }) |
| if !found { |
| return 0, MappedRange{}, ErrNoRuneFound |
| } |
| |
| var r rune |
| var start, end token.Pos |
| switch lit.Kind { |
| case token.CHAR: |
| s, err := strconv.Unquote(lit.Value) |
| if err != nil { |
| // If the conversion fails, it's because of an invalid syntax, therefore |
| // there is no rune to be found. |
| return 0, MappedRange{}, ErrNoRuneFound |
| } |
| r, _ = utf8.DecodeRuneInString(s) |
| if r == utf8.RuneError { |
| return 0, MappedRange{}, fmt.Errorf("rune error") |
| } |
| start, end = lit.Pos(), lit.End() |
| case token.INT: |
| // It's an integer, scan only if it is a hex litteral whose bitsize in |
| // ranging from 8 to 32. |
| if !(strings.HasPrefix(lit.Value, "0x") && len(lit.Value[2:]) >= 2 && len(lit.Value[2:]) <= 8) { |
| return 0, MappedRange{}, ErrNoRuneFound |
| } |
| v, err := strconv.ParseUint(lit.Value[2:], 16, 32) |
| if err != nil { |
| return 0, MappedRange{}, err |
| } |
| r = rune(v) |
| if r == utf8.RuneError { |
| return 0, MappedRange{}, fmt.Errorf("rune error") |
| } |
| start, end = lit.Pos(), lit.End() |
| case token.STRING: |
| // It's a string, scan only if it contains a unicode escape sequence under or before the |
| // current cursor position. |
| var found bool |
| litOffset, err := safetoken.Offset(pgf.Tok, lit.Pos()) |
| if err != nil { |
| return 0, MappedRange{}, err |
| } |
| offset, err := safetoken.Offset(pgf.Tok, pos) |
| if err != nil { |
| return 0, MappedRange{}, err |
| } |
| for i := offset - litOffset; i > 0; i-- { |
| // Start at the cursor position and search backward for the beginning of a rune escape sequence. |
| rr, _ := utf8.DecodeRuneInString(lit.Value[i:]) |
| if rr == utf8.RuneError { |
| return 0, MappedRange{}, fmt.Errorf("rune error") |
| } |
| if rr == '\\' { |
| // Got the beginning, decode it. |
| var tail string |
| r, _, tail, err = strconv.UnquoteChar(lit.Value[i:], '"') |
| if err != nil { |
| // If the conversion fails, it's because of an invalid syntax, therefore is no rune to be found. |
| return 0, MappedRange{}, ErrNoRuneFound |
| } |
| // Only the rune escape sequence part of the string has to be highlighted, recompute the range. |
| runeLen := len(lit.Value) - (int(i) + len(tail)) |
| start = token.Pos(int(lit.Pos()) + int(i)) |
| end = token.Pos(int(start) + runeLen) |
| found = true |
| break |
| } |
| } |
| if !found { |
| // No escape sequence found |
| return 0, MappedRange{}, ErrNoRuneFound |
| } |
| default: |
| return 0, MappedRange{}, ErrNoRuneFound |
| } |
| |
| mappedRange, err := posToMappedRange(snapshot, pkg, start, end) |
| if err != nil { |
| return 0, MappedRange{}, err |
| } |
| return r, mappedRange, nil |
| } |
| |
| func HoverIdentifier(ctx context.Context, i *IdentifierInfo) (*HoverJSON, error) { |
| ctx, done := event.Start(ctx, "source.Hover") |
| defer done() |
| |
| hoverCtx, err := FindHoverContext(ctx, i.Snapshot, i.pkg, i.Declaration.obj, i.Declaration.node, i.Declaration.fullDecl) |
| if err != nil { |
| return nil, err |
| } |
| |
| h := &HoverJSON{ |
| FullDocumentation: hoverCtx.Comment.Text(), |
| Synopsis: doc.Synopsis(hoverCtx.Comment.Text()), |
| } |
| |
| fset := i.Snapshot.FileSet() |
| // Determine the symbol's signature. |
| switch x := hoverCtx.signatureSource.(type) { |
| case string: |
| h.Signature = x // a pre-computed signature |
| |
| case *ast.TypeSpec: |
| x2 := *x |
| // Don't duplicate comments when formatting type specs. |
| x2.Doc = nil |
| x2.Comment = nil |
| var b strings.Builder |
| b.WriteString("type ") |
| if err := format.Node(&b, fset, &x2); err != nil { |
| return nil, err |
| } |
| h.Signature = b.String() |
| |
| case ast.Node: |
| var b strings.Builder |
| if err := format.Node(&b, fset, x); err != nil { |
| return nil, err |
| } |
| h.Signature = b.String() |
| |
| // Check if the variable is an integer whose value we can present in a more |
| // user-friendly way, i.e. `var hex = 0xe34e` becomes `var hex = 58190` |
| if spec, ok := x.(*ast.ValueSpec); ok && len(spec.Values) > 0 { |
| if lit, ok := spec.Values[0].(*ast.BasicLit); ok && len(spec.Names) > 0 { |
| val := constant.MakeFromLiteral(types.ExprString(lit), lit.Kind, 0) |
| h.Signature = fmt.Sprintf("var %s = %s", spec.Names[0], val) |
| } |
| } |
| |
| case types.Object: |
| // If the variable is implicitly declared in a type switch, we need to |
| // manually generate its object string. |
| if typ := i.Declaration.typeSwitchImplicit; typ != nil { |
| if v, ok := x.(*types.Var); ok { |
| h.Signature = fmt.Sprintf("var %s %s", v.Name(), types.TypeString(typ, i.qf)) |
| break |
| } |
| } |
| h.Signature = objectString(x, i.qf, i.Inferred) |
| } |
| if obj := i.Declaration.obj; obj != nil { |
| h.SingleLine = objectString(obj, i.qf, nil) |
| } |
| obj := i.Declaration.obj |
| if obj == nil { |
| return h, nil |
| } |
| |
| // Check if the identifier is test-only (and is therefore not part of a |
| // package's API). This is true if the request originated in a test package, |
| // and if the declaration is also found in the same test package. |
| if i.pkg != nil && obj.Pkg() != nil && i.pkg.ForTest() != "" { |
| if _, err := i.pkg.File(i.Declaration.MappedRange[0].URI()); err == nil { |
| return h, nil |
| } |
| } |
| |
| h.SymbolName, h.LinkPath, h.LinkAnchor = linkData(obj, i.enclosing) |
| |
| // See golang/go#36998: don't link to modules matching GOPRIVATE. |
| // |
| // The path returned by linkData is an import path. |
| if i.Snapshot.View().IsGoPrivatePath(h.LinkPath) { |
| h.LinkPath = "" |
| } else if mod, version, ok := moduleAtVersion(h.LinkPath, i); ok { |
| h.LinkPath = strings.Replace(h.LinkPath, mod, mod+"@"+version, 1) |
| } |
| |
| return h, nil |
| } |
| |
| // linkData returns the name, import path, and anchor to use in building links |
| // to obj. |
| // |
| // If obj is not visible in documentation, the returned name will be empty. |
| func linkData(obj types.Object, enclosing *types.TypeName) (name, importPath, anchor string) { |
| // Package names simply link to the package. |
| if obj, ok := obj.(*types.PkgName); ok { |
| return obj.Name(), obj.Imported().Path(), "" |
| } |
| |
| // Builtins link to the special builtin package. |
| if obj.Parent() == types.Universe { |
| return obj.Name(), "builtin", obj.Name() |
| } |
| |
| // In all other cases, the object must be exported. |
| if !obj.Exported() { |
| return "", "", "" |
| } |
| |
| var recv types.Object // If non-nil, the field or method receiver base. |
| |
| switch obj := obj.(type) { |
| case *types.Var: |
| // If the object is a field, and we have an associated selector |
| // composite literal, or struct, we can determine the link. |
| if obj.IsField() && enclosing != nil { |
| recv = enclosing |
| } |
| case *types.Func: |
| typ, ok := obj.Type().(*types.Signature) |
| if !ok { |
| // Note: this should never happen. go/types guarantees that the type of |
| // *Funcs are Signatures. |
| // |
| // TODO(rfindley): given a 'debug' mode, we should panic here. |
| return "", "", "" |
| } |
| if r := typ.Recv(); r != nil { |
| if rtyp, _ := Deref(r.Type()).(*types.Named); rtyp != nil { |
| // If we have an unexported type, see if the enclosing type is |
| // exported (we may have an interface or struct we can link |
| // to). If not, don't show any link. |
| if !rtyp.Obj().Exported() { |
| if enclosing != nil { |
| recv = enclosing |
| } else { |
| return "", "", "" |
| } |
| } else { |
| recv = rtyp.Obj() |
| } |
| } |
| } |
| } |
| |
| if recv != nil && !recv.Exported() { |
| return "", "", "" |
| } |
| |
| // Either the object or its receiver must be in the package scope. |
| scopeObj := obj |
| if recv != nil { |
| scopeObj = recv |
| } |
| if scopeObj.Pkg() == nil || scopeObj.Pkg().Scope().Lookup(scopeObj.Name()) != scopeObj { |
| return "", "", "" |
| } |
| |
| // golang/go#52211: somehow we get here with a nil obj.Pkg |
| if obj.Pkg() == nil { |
| bug.Report("object with nil pkg", bug.Data{ |
| "name": obj.Name(), |
| "type": fmt.Sprintf("%T", obj), |
| }) |
| return "", "", "" |
| } |
| |
| importPath = obj.Pkg().Path() |
| if recv != nil { |
| anchor = fmt.Sprintf("%s.%s", recv.Name(), obj.Name()) |
| name = fmt.Sprintf("(%s.%s).%s", obj.Pkg().Name(), recv.Name(), obj.Name()) |
| } else { |
| // For most cases, the link is "package/path#symbol". |
| anchor = obj.Name() |
| name = fmt.Sprintf("%s.%s", obj.Pkg().Name(), obj.Name()) |
| } |
| return name, importPath, anchor |
| } |
| |
| func moduleAtVersion(path string, i *IdentifierInfo) (string, string, bool) { |
| // TODO(rfindley): moduleAtVersion should not be responsible for deciding |
| // whether or not the link target supports module version links. |
| if strings.ToLower(i.Snapshot.View().Options().LinkTarget) != "pkg.go.dev" { |
| return "", "", false |
| } |
| impPkg, err := i.pkg.GetImport(path) |
| if err != nil { |
| return "", "", false |
| } |
| if impPkg.Version() == nil { |
| return "", "", false |
| } |
| version, modpath := impPkg.Version().Version, impPkg.Version().Path |
| if modpath == "" || version == "" { |
| return "", "", false |
| } |
| return modpath, version, true |
| } |
| |
| // objectString is a wrapper around the types.ObjectString function. |
| // It handles adding more information to the object string. |
| func objectString(obj types.Object, qf types.Qualifier, inferred *types.Signature) string { |
| // If the signature type was inferred, prefer the preferred signature with a |
| // comment showing the generic signature. |
| if sig, _ := obj.Type().(*types.Signature); sig != nil && typeparams.ForSignature(sig).Len() > 0 && inferred != nil { |
| obj2 := types.NewFunc(obj.Pos(), obj.Pkg(), obj.Name(), inferred) |
| str := types.ObjectString(obj2, qf) |
| // Try to avoid overly long lines. |
| if len(str) > 60 { |
| str += "\n" |
| } else { |
| str += " " |
| } |
| str += "// " + types.TypeString(sig, qf) |
| return str |
| } |
| str := types.ObjectString(obj, qf) |
| switch obj := obj.(type) { |
| case *types.Const: |
| str = fmt.Sprintf("%s = %s", str, obj.Val()) |
| |
| // Try to add a formatted duration as an inline comment |
| typ, ok := obj.Type().(*types.Named) |
| if !ok { |
| break |
| } |
| pkg := typ.Obj().Pkg() |
| if pkg.Path() == "time" && typ.Obj().Name() == "Duration" { |
| if d, ok := constant.Int64Val(obj.Val()); ok { |
| str += " // " + time.Duration(d).String() |
| } |
| } |
| } |
| return str |
| } |
| |
| // FindHoverContext returns a HoverContext struct for an AST node and its |
| // declaration object. node should be the actual node used in type checking, |
| // while fullNode could be a separate node with more complete syntactic |
| // information. |
| func FindHoverContext(ctx context.Context, s Snapshot, pkg Package, obj types.Object, pkgNode ast.Node, fullDecl ast.Decl) (*HoverContext, error) { |
| var info *HoverContext |
| |
| // Type parameters get their signature from their declaration object. |
| if _, isTypeName := obj.(*types.TypeName); isTypeName { |
| if _, isTypeParam := obj.Type().(*typeparams.TypeParam); isTypeParam { |
| return &HoverContext{signatureSource: obj}, nil |
| } |
| } |
| |
| // This is problematic for a number of reasons. We really need to have a more |
| // general mechanism to validate the coherency of AST with type information, |
| // but absent that we must do our best to ensure that we don't use fullNode |
| // when we actually need the node that was type checked. |
| // |
| // pkgNode may be nil, if it was eliminated from the type-checked syntax. In |
| // that case, use fullDecl if available. |
| node := pkgNode |
| if node == nil && fullDecl != nil { |
| node = fullDecl |
| } |
| |
| switch node := node.(type) { |
| case *ast.Ident: |
| // The package declaration. |
| for _, f := range pkg.GetSyntax() { |
| if f.Name == pkgNode { |
| info = &HoverContext{Comment: f.Doc} |
| } |
| } |
| case *ast.ImportSpec: |
| // Try to find the package documentation for an imported package. |
| pkgPath, err := strconv.Unquote(node.Path.Value) |
| if err != nil { |
| return nil, err |
| } |
| imp, err := pkg.GetImport(pkgPath) |
| if err != nil { |
| return nil, err |
| } |
| // Assume that only one file will contain package documentation, |
| // so pick the first file that has a doc comment. |
| for _, file := range imp.GetSyntax() { |
| if file.Doc != nil { |
| info = &HoverContext{Comment: file.Doc} |
| if file.Name != nil { |
| info.signatureSource = "package " + file.Name.Name |
| } |
| break |
| } |
| } |
| case *ast.GenDecl: |
| switch obj := obj.(type) { |
| case *types.TypeName, *types.Var, *types.Const, *types.Func: |
| // Always use the full declaration here if we have it, because the |
| // dependent code doesn't rely on pointer identity. This is fragile. |
| if d, _ := fullDecl.(*ast.GenDecl); d != nil { |
| node = d |
| } |
| // obj may not have been produced by type checking the AST containing |
| // node, so we need to be careful about using token.Pos. |
| tok := s.FileSet().File(obj.Pos()) |
| offset, err := safetoken.Offset(tok, obj.Pos()) |
| if err != nil { |
| return nil, err |
| } |
| |
| // fullTok and fullPos are the *token.File and object position in for the |
| // full AST. |
| fullTok := s.FileSet().File(node.Pos()) |
| fullPos, err := safetoken.Pos(fullTok, offset) |
| if err != nil { |
| return nil, err |
| } |
| |
| var spec ast.Spec |
| for _, s := range node.Specs { |
| // Avoid panics by guarding the calls to token.Offset (golang/go#48249). |
| start, err := safetoken.Offset(fullTok, s.Pos()) |
| if err != nil { |
| return nil, err |
| } |
| end, err := safetoken.Offset(fullTok, s.End()) |
| if err != nil { |
| return nil, err |
| } |
| if start <= offset && offset <= end { |
| spec = s |
| break |
| } |
| } |
| |
| info, err = hoverGenDecl(node, spec, fullPos, obj) |
| if err != nil { |
| return nil, err |
| } |
| } |
| case *ast.TypeSpec: |
| if obj.Parent() == types.Universe { |
| if genDecl, ok := fullDecl.(*ast.GenDecl); ok { |
| info = hoverTypeSpec(node, genDecl) |
| } |
| } |
| case *ast.FuncDecl: |
| switch obj.(type) { |
| case *types.Func: |
| info = &HoverContext{signatureSource: obj, Comment: node.Doc} |
| case *types.Builtin: |
| info = &HoverContext{Comment: node.Doc} |
| if sig, err := NewBuiltinSignature(ctx, s, obj.Name()); err == nil { |
| info.signatureSource = "func " + sig.name + sig.Format() |
| } else { |
| // Fall back on the object as a signature source. |
| bug.Report("invalid builtin hover", bug.Data{ |
| "err": err.Error(), |
| }) |
| info.signatureSource = obj |
| } |
| case *types.Var: |
| // Object is a function param or the field of an anonymous struct |
| // declared with ':='. Skip the first one because only fields |
| // can have docs. |
| if isFunctionParam(obj, node) { |
| break |
| } |
| |
| _, field := FindDeclAndField(pkg.GetSyntax(), obj.Pos()) |
| if field != nil { |
| comment := field.Doc |
| if comment.Text() == "" { |
| comment = field.Comment |
| } |
| info = &HoverContext{signatureSource: obj, Comment: comment} |
| } |
| } |
| } |
| |
| if info == nil { |
| info = &HoverContext{signatureSource: obj} |
| } |
| |
| return info, nil |
| } |
| |
| // isFunctionParam returns true if the passed object is either an incoming |
| // or an outgoing function param |
| func isFunctionParam(obj types.Object, node *ast.FuncDecl) bool { |
| for _, f := range node.Type.Params.List { |
| if f.Pos() == obj.Pos() { |
| return true |
| } |
| } |
| if node.Type.Results != nil { |
| for _, f := range node.Type.Results.List { |
| if f.Pos() == obj.Pos() { |
| return true |
| } |
| } |
| } |
| return false |
| } |
| |
| // hoverGenDecl returns hover information an object declared via spec inside |
| // of the GenDecl node. obj is the type-checked object corresponding to the |
| // declaration, but may have been type-checked using a different AST than the |
| // given nodes; fullPos is the position of obj in node's AST. |
| func hoverGenDecl(node *ast.GenDecl, spec ast.Spec, fullPos token.Pos, obj types.Object) (*HoverContext, error) { |
| if spec == nil { |
| return nil, fmt.Errorf("no spec for node %v at position %v", node, fullPos) |
| } |
| |
| // If we have a field or method. |
| switch obj.(type) { |
| case *types.Var, *types.Const, *types.Func: |
| return hoverVar(spec, fullPos, obj, node), nil |
| } |
| // Handle types. |
| switch spec := spec.(type) { |
| case *ast.TypeSpec: |
| return hoverTypeSpec(spec, node), nil |
| case *ast.ValueSpec: |
| return &HoverContext{signatureSource: spec, Comment: spec.Doc}, nil |
| case *ast.ImportSpec: |
| return &HoverContext{signatureSource: spec, Comment: spec.Doc}, nil |
| } |
| return nil, fmt.Errorf("unable to format spec %v (%T)", spec, spec) |
| } |
| |
| // TODO(rfindley): rename this function. |
| func hoverTypeSpec(spec *ast.TypeSpec, decl *ast.GenDecl) *HoverContext { |
| comment := spec.Doc |
| if comment == nil && decl != nil { |
| comment = decl.Doc |
| } |
| if comment == nil { |
| comment = spec.Comment |
| } |
| return &HoverContext{ |
| signatureSource: spec, |
| Comment: comment, |
| } |
| } |
| |
| func hoverVar(node ast.Spec, fullPos token.Pos, obj types.Object, decl *ast.GenDecl) *HoverContext { |
| var fieldList *ast.FieldList |
| switch spec := node.(type) { |
| case *ast.TypeSpec: |
| switch t := spec.Type.(type) { |
| case *ast.StructType: |
| fieldList = t.Fields |
| case *ast.InterfaceType: |
| fieldList = t.Methods |
| } |
| case *ast.ValueSpec: |
| // Try to extract the field list of an anonymous struct |
| if fieldList = extractFieldList(spec.Type); fieldList != nil { |
| break |
| } |
| |
| comment := spec.Doc |
| if comment == nil { |
| comment = decl.Doc |
| } |
| if comment == nil { |
| comment = spec.Comment |
| } |
| |
| // We need the AST nodes for variable declarations of basic literals with |
| // associated values so that we can augment their hover with more information. |
| if _, ok := obj.(*types.Var); ok && spec.Type == nil && len(spec.Values) > 0 { |
| if _, ok := spec.Values[0].(*ast.BasicLit); ok { |
| return &HoverContext{signatureSource: spec, Comment: comment} |
| } |
| } |
| |
| return &HoverContext{signatureSource: obj, Comment: comment} |
| } |
| |
| if fieldList != nil { |
| comment := findFieldComment(fullPos, fieldList) |
| return &HoverContext{signatureSource: obj, Comment: comment} |
| } |
| return &HoverContext{signatureSource: obj, Comment: decl.Doc} |
| } |
| |
| // extractFieldList recursively tries to extract a field list. |
| // If it is not found, nil is returned. |
| func extractFieldList(specType ast.Expr) *ast.FieldList { |
| switch t := specType.(type) { |
| case *ast.StructType: |
| return t.Fields |
| case *ast.InterfaceType: |
| return t.Methods |
| case *ast.ArrayType: |
| return extractFieldList(t.Elt) |
| case *ast.MapType: |
| // Map value has a greater chance to be a struct |
| if fields := extractFieldList(t.Value); fields != nil { |
| return fields |
| } |
| return extractFieldList(t.Key) |
| case *ast.ChanType: |
| return extractFieldList(t.Value) |
| } |
| return nil |
| } |
| |
| // findFieldComment visits all fields in depth-first order and returns |
| // the comment of a field with passed position. If no comment is found, |
| // nil is returned. |
| func findFieldComment(pos token.Pos, fieldList *ast.FieldList) *ast.CommentGroup { |
| for _, field := range fieldList.List { |
| if field.Pos() == pos { |
| if field.Doc.Text() != "" { |
| return field.Doc |
| } |
| return field.Comment |
| } |
| |
| if nestedFieldList := extractFieldList(field.Type); nestedFieldList != nil { |
| if c := findFieldComment(pos, nestedFieldList); c != nil { |
| return c |
| } |
| } |
| } |
| return nil |
| } |
| |
| func FormatHover(h *HoverJSON, options *Options) (string, error) { |
| signature := formatSignature(h, options) |
| |
| switch options.HoverKind { |
| case SingleLine: |
| return h.SingleLine, nil |
| case NoDocumentation: |
| return signature, nil |
| case Structured: |
| b, err := json.Marshal(h) |
| if err != nil { |
| return "", err |
| } |
| return string(b), nil |
| } |
| |
| link := formatLink(h, options) |
| doc := formatDoc(h, options) |
| |
| var b strings.Builder |
| parts := []string{signature, doc, link} |
| for i, el := range parts { |
| if el != "" { |
| b.WriteString(el) |
| |
| // Don't write out final newline. |
| if i == len(parts) { |
| continue |
| } |
| // If any elements of the remainder of the list are non-empty, |
| // write a newline. |
| if anyNonEmpty(parts[i+1:]) { |
| if options.PreferredContentFormat == protocol.Markdown { |
| b.WriteString("\n\n") |
| } else { |
| b.WriteRune('\n') |
| } |
| } |
| } |
| } |
| return b.String(), nil |
| } |
| |
| func formatSignature(h *HoverJSON, options *Options) string { |
| signature := h.Signature |
| if signature != "" && options.PreferredContentFormat == protocol.Markdown { |
| signature = fmt.Sprintf("```go\n%s\n```", signature) |
| } |
| return signature |
| } |
| |
| func formatLink(h *HoverJSON, options *Options) string { |
| if !options.LinksInHover || options.LinkTarget == "" || h.LinkPath == "" { |
| return "" |
| } |
| plainLink := BuildLink(options.LinkTarget, h.LinkPath, h.LinkAnchor) |
| switch options.PreferredContentFormat { |
| case protocol.Markdown: |
| return fmt.Sprintf("[`%s` on %s](%s)", h.SymbolName, options.LinkTarget, plainLink) |
| case protocol.PlainText: |
| return "" |
| default: |
| return plainLink |
| } |
| } |
| |
| // BuildLink constructs a link with the given target, path, and anchor. |
| func BuildLink(target, path, anchor string) string { |
| link := fmt.Sprintf("https://%s/%s", target, path) |
| if target == "pkg.go.dev" { |
| link += "?utm_source=gopls" |
| } |
| if anchor == "" { |
| return link |
| } |
| return link + "#" + anchor |
| } |
| |
| func formatDoc(h *HoverJSON, options *Options) string { |
| var doc string |
| switch options.HoverKind { |
| case SynopsisDocumentation: |
| doc = h.Synopsis |
| case FullDocumentation: |
| doc = h.FullDocumentation |
| } |
| if options.PreferredContentFormat == protocol.Markdown { |
| return CommentToMarkdown(doc) |
| } |
| return doc |
| } |
| |
| func anyNonEmpty(x []string) bool { |
| for _, el := range x { |
| if el != "" { |
| return true |
| } |
| } |
| return false |
| } |
| |
| // FindDeclAndField returns the var/func/type/const Decl that declares |
| // the identifier at pos, searching the given list of file syntax |
| // trees. If pos is the position of an ast.Field or one of its Names |
| // or Ellipsis.Elt, the field is returned, along with the innermost |
| // enclosing Decl, which could be only loosely related---consider: |
| // |
| // var decl = f( func(field int) {} ) |
| // |
| // It returns (nil, nil) if no Field or Decl is found at pos. |
| func FindDeclAndField(files []*ast.File, pos token.Pos) (decl ast.Decl, field *ast.Field) { |
| // panic(nil) breaks off the traversal and |
| // causes the function to return normally. |
| defer func() { |
| if x := recover(); x != nil { |
| panic(x) |
| } |
| }() |
| |
| // Visit the files in search of the node at pos. |
| var stack []ast.Node |
| for _, file := range files { |
| ast.Inspect(file, func(n ast.Node) bool { |
| if n != nil { |
| stack = append(stack, n) // push |
| } else { |
| stack = stack[:len(stack)-1] // pop |
| return false |
| } |
| |
| // Skip subtrees (incl. files) that don't contain the search point. |
| if !(n.Pos() <= pos && pos < n.End()) { |
| return false |
| } |
| |
| switch n := n.(type) { |
| case *ast.Field: |
| checkField := func(f ast.Node) { |
| if f.Pos() == pos { |
| field = n |
| for i := len(stack) - 1; i >= 0; i-- { |
| if d, ok := stack[i].(ast.Decl); ok { |
| decl = d // innermost enclosing decl |
| break |
| } |
| } |
| panic(nil) // found |
| } |
| } |
| |
| // Check *ast.Field itself. This handles embedded |
| // fields which have no associated *ast.Ident name. |
| checkField(n) |
| |
| // Check each field name since you can have |
| // multiple names for the same type expression. |
| for _, name := range n.Names { |
| checkField(name) |
| } |
| |
| // Also check "X" in "...X". This makes it easy |
| // to format variadic signature params properly. |
| if ell, ok := n.Type.(*ast.Ellipsis); ok && ell.Elt != nil { |
| checkField(ell.Elt) |
| } |
| |
| case *ast.FuncDecl: |
| if n.Name.Pos() == pos { |
| decl = n |
| panic(nil) // found |
| } |
| |
| case *ast.GenDecl: |
| for _, spec := range n.Specs { |
| switch spec := spec.(type) { |
| case *ast.TypeSpec: |
| if spec.Name.Pos() == pos { |
| decl = n |
| panic(nil) // found |
| } |
| case *ast.ValueSpec: |
| for _, id := range spec.Names { |
| if id.Pos() == pos { |
| decl = n |
| panic(nil) // found |
| } |
| } |
| } |
| } |
| } |
| return true |
| }) |
| } |
| |
| return nil, nil |
| } |