.config/coc/extensions/coc-go-data/tools/pkg/mod/golang.org/x/tools/gopls@v0.5.2/doc/integrating.md

   1 # Documentation for plugin authors
   2
   3 If you are integrating `gopls` into an editor by writing an editor plugin, there are quite a few semantics of the communication between the editor and `gopls` that are not specified by the [LSP specification].
   4
   5 We attempt to document those details along with any other information that has been helpful to other plugin authors here.
   6
   7 If you are implementing a plugin yourself and have questions this page does not answer, please reach out to us to ask, and then also contribute your findings back to this page.
   8
   9 ## Supported features
  10
  11 For the most part you should look at the [list](status.md#supported-features) in the current status document to know if gopls supports a feature.
  12 For a truly authoritative answer you should check the [result][InitializeResult] of the [initialize] request, where gopls enumerates its support in the [ServerCapabilities].
  13
  14
  15 ## Positions and ranges
  16
  17 Many LSP requests pass position or range information. This is described in the [LSP specification][lsp-text-documents]:
  18
  19 > A position inside a document (see Position definition below) is expressed as a zero-based line and character offset. The offsets are based on a UTF-16 string representation. So a string of the form a𐐀b the character offset of the character a is 0, the character offset of 𐐀 is 1 and the character offset of b is 3 since 𐐀 is represented using two code units in UTF-16.
  20
  21 This means that integrators will need to calculate UTF-16 based column offsets.
  22
  23 [`golang.org/x/tools/internal/span`] has the code to do this in go.
  24 [#31080] tracks making `span` and other useful packages non-internal.
  25
  26 ## Edits
  27
  28 In order to deliver changes from gopls to the editor, the LSP supports arrays of [`TextEdit`][lsp-textedit]s in responses.
  29 The spec specifies exactly how these should be applied:
  30
  31 > All text edits ranges refer to positions in the original document. Text edits ranges must never overlap, that means no part of the original document must be manipulated by more than one edit. However, it is possible that multiple edits have the same start position: multiple inserts, or any number of inserts followed by a single remove or replace edit. If multiple inserts have the same position, the order in the array defines the order in which the inserted strings appear in the resulting text.
  32
  33 All `[]TextEdit` are sorted such that applying the array of deltas received in reverse order achieves the desired result that holds with the spec.
  34
  35 ## Errors
  36
  37 Various error codes are described in the [LSP specification][lsp-response]. We are still determining what it means for a method to return an error; are errors only for low-level LSP/transport issues or can other conditions cause errors to be returned? See some of this discussion on [#31526].
  38
  39 The method chosen is currently influenced by the exact treatment in the currently popular editor integrations. It may well change, and ideally would become more coherent across requests.
  40
  41 * [`textDocument/codeAction`]: Return error if there was an error computing code actions.
  42 * [`textDocument/completion`]: Log errors, return empty result list.
  43 * [`textDocument/definition`]: Return error if there was an error computing the definition for the position.
  44 * [`textDocument/typeDefinition`]: Return error if there was an error computing the type definition for the position.
  45 * [`textDocument/formatting`]: Return error if there was an error formatting the file.
  46 * [`textDocument/highlight`]: Log errors, return empty result.
  47 * [`textDocument/hover`]: Return empty result.
  48 * [`textDocument/documentLink`]: Log errors, return nil result.
  49 * [`textDocument/publishDiagnostics`]: Log errors if there were any while computing diagnostics.
  50 * [`textDocument/references`]: Log errors, return empty result.
  51 * [`textDocument/rename`]: Return error if there was an error computing renames.
  52 * [`textDocument/signatureHelp`]: Log errors, return nil result.
  53 * [`textDocument/documentSymbols`]: Return error if there was an error computing document symbols.
  54
  55 ## Watching files
  56
  57 It is fairly normal for files that affect `gopls` to be modified outside of the editor it is associated with.
  58
  59 For instance, files that are needed to do correct type checking are modified by switching branches in git, or updated by a code generator.
  60
  61 Monitoring files inside gopls directly has a lot of awkward problems, but the [LSP specification] has methods that allow gopls to request that the client notify it of file system changes, specifically [`workspace/didChangeWatchedFiles`].
  62 This is currently being added to gopls by a community member, and tracked in [#31553]
  63
  64 [InitializeResult]: https://godoc.org/golang.org/x/tools/internal/lsp/protocol#InitializeResult
  65 [ServerCapabilities]: https://godoc.org/golang.org/x/tools/internal/lsp/protocol#ServerCapabilities
  66 [`golang.org/x/tools/internal/span`]: https://godoc.org/golang.org/x/tools/internal/span#NewPoint
  67
  68 [LSP specification]: https://microsoft.github.io/language-server-protocol/specifications/specification-3-14/
  69 [lsp-response]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#response-message
  70 [initialize]: https://microsoft.github.io/language-server-protocol/specifications/specification-3-14/#initialize
  71 [lsp-text-documents]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#text-documents
  72 [lsp-textedit]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textedit
  73
  74 [`textDocument/codeAction`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_codeAction
  75 [`textDocument/completion`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_completion
  76 [`textDocument/definition`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_definition
  77 [`textDocument/typeDefinition`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_typeDefinition
  78 [`textDocument/formatting`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_formatting
  79 [`textDocument/highlight`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_highlight
  80 [`textDocument/hover`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_hover
  81 [`textDocument/documentLink`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_documentLink
  82 [`textDocument/publishDiagnostics`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_publishDiagnostics
  83 [`textDocument/references`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_references
  84 [`textDocument/rename`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_rename
  85 [`textDocument/signatureHelp`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_signatureHelp
  86 [`textDocument/documentSymbols`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_documentSymbols
  87 [`workspace/didChangeWatchedFiles`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#workspace_didChangeWatchedFiles
  88
  89 [#31080]: https://github.com/golang/go/issues/31080
  90 [#31553]: https://github.com/golang/go/issues/31553
  91 [#31526]: https://github.com/golang/go/issues/31526