This page documents the fundamental LSP features of gopls that may be described as “passive”, since many editors use them to continuously provide information about your source files without requiring any special action.
See also Code Lenses, some of which annotate your source code with additional information and may thus also be considered passive features.
The LSP textDocument/hover query returns description of the code currently under the cursor, such as its name, kind, type, value (for a constant), abbreviated declaration (for a type), its doc comment, if any, and a link to the symbol's documentation on pkg.go.dev. The client may request either plain text or Markdown.
Depending on the selection, it may include additional information. For example, hovering over a type shows its declared methods, plus any methods promoted from embedded fields.
Doc links: A doc comment may refer to another symbol using square brackets, for example [fmt.Printf]. Hovering over one of these doc links reveals information about the referenced symbol.
Struct size/offset info: for declarations of struct types, hovering over the name reveals the struct's size in bytes:
And hovering over each field name shows the size and offset of that field:
This information may be useful when optimizing the layout of your data structures, or when reading assembly files or stack traces that refer to each field by its cryptic byte offset.
In addition, Hover reports the percentage of wasted space due to suboptimal ordering of struct fields, if this figure is 20% or higher:
In the struct above, alignment rules require each of the two boolean fields (1 byte) to occupy a complete word (8 bytes), leading to (7 + 7) / (3 * 8) = 58% waste. Placing the two booleans together would save a word. (In most structures clarity is more important than compactness, so you should reorder fields to save space only in data structures that have been shown by profiling to be very frequently allocated.)
Embed directives: hovering over the file name pattern in //go:embed directive, for example *.html, reveals the list of file names to which the wildcard expands.
Linkname directives: a //go:linkname directive creates a linker-level alias for another symbol. Hovering over the directive shows information about the other symbol.
The hover information for symbols from the standard library added after Go 1.0 states the Go release that added the symbol.
Settings:
hoverKind setting controls the verbosity of documentation.linkTarget setting specifies the base URI for Go package linksCaveats:
Hover request currently includes only a position but not a selection, as this means it is impossible to request information about the type and methods of, say, the f(x) portion of the larger expression f(x).y. Please upvote microsoft/language-server-protocol#1466 if you would like to see this addressed.Client support:
gopls definition file.go:#start-#end includes information from a Hover query.The LSP textDocument/signatureHelp query returns information about the innermost function call enclosing the cursor or selection, including the signature of the function and the names, types, and documentation of each parameter.
Clients may provide this information to help remind the user of the purpose of each parameter and their order, while reading or editing a function call.
Client support:
gopls signature file.go:#start-#endThe LSP textDocument/documentHighlight query reports a set of source ranges that should be highlighted based on the current cursor position or selection, to emphasize the relationship between them.
Each of the following parts of syntax forms a set so that if you select any one member, gopls will highlight the complete set:
return statements;for, break, and continue tokens of the same loop;switch and break tokens of the same switch statement;func keyword of a function and all of its return statements.More than one of these rules may be activated by the same selection, for example, an identifier that is also a return operand.
Client support:
gopls signature file.go:#start-#endThe LSP textDocument/inlayHint query returns a set of annotations to be spliced into the current file that reveal implicit information.
Examples:
f(1, 2), gopls will provide hints for the names of the parameters (parameterNames), as in the screenshot above.functionTypeParameters).x, y = 1, 2, hints provide the types of the variables (assignVariableTypes).Point2D{1, 2}, hints provide the field names (compositeLiteralFields).T{{...}}, a hint provides the type of the inner literal, {...} (compositeLiteralTypes).for k, v := range x {} loop, hints provide the types of the variables k and v (rangeVariableTypes).iota), a hint provides its computed value (constantValues).See Inlay hints for a complete list with examples.
TODO: Do we really need that separate doc? We could put all the information here with much less fuss. It changes so rarely that a culture of “update the tests and docs in every CL” should be sufficient. IIUC, VS Code needs only the api-json representation.
Settings:
hints setting indicates the desired set of hints. To reduce distractions, its default value is empty. To enable hints, add one or more of the identifiers above to the hints map. For example:"hints": {"parameterNames": true}
Client support:
hints configuration value, VS Code provides a graphical configuration menu (“Preferences: Open Settings (UI)” the search for “Go Inlay Hints”) for each supported kind of inlay hint.M-x eglot-inlay-hints-mode plus the configuration described hereThe LSP textDocument/semanticTokens query reports information about all the tokens in the current file, or a portion of it. The client may use this information to provide syntax highlighting that conveys semantic distinctions between, for example, functions and types, constants and variables, or library functions and built-ins. The client specifies the sets of types and modifiers they are interested in.
Settings:
semanticTokens setting determines whether gopls responds to semantic token requests. This option allows users to disable semantic tokens even when their client provides no client-side control over the feature. Because gopls' semantic-tokens algorithm depends on type checking, which adds a tangible latency, this feature is currently disabled by default to avoid any delay in syntax highlighting; see golang/go#45313, golang/go#47465.noSemanticString and noSemanticNumber settings cause the server to exclude the string and number kinds from the response, as some clients may do a more colorful job highlighting these tokens; see golang/go#45753.Client Support:
gopls semtok file.goFor internal details of gopls' implementation of semantic tokens, see semantic tokens.
The LSP textDocument/foldingRange query reports the list of regions in the current file that may be independently collapsed or expanded. For example, it may be convenient to collapse large comments or functions when studying some code so that more of it fits in a single screen.
The protocol allows clients to indicate whether they prefer fine-grained ranges such as matched pairs of brackets, or only ranges consisting of complete lines.
Client support:
∨ and >) to collapse or expand.gopls folding_ranges file.goThe LSP textDocument/documentLink query uses heuristics to extracts URLs from doc comments and string literals in the current file so that client can present them as clickable links.
In addition to explicit URLs, gopls also turns string literals in import declarations into links to the pkg.go.dev documentation for the imported package.
Settings:
importShortcut setting determines what kind of link is returned for an import declaration.linkTarget setting specifies the base URI for Go package links.Client support:
gopls links file.go