diff options
Diffstat (limited to 'runtime/doc/lsp.txt')
| -rw-r--r-- | runtime/doc/lsp.txt | 131 |
1 files changed, 60 insertions, 71 deletions
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index c4322e9c24..bc924df39b 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -46,38 +46,40 @@ Follow these steps to get LSP features: See |lsp-config|. *lsp-config* - -Starting a LSP client will automatically report diagnostics via -|vim.diagnostic|. Read |vim.diagnostic.config()| to learn how to customize the -display. - -It also sets some buffer options if the language server supports the -functionality and if the options are otherwise empty or have the default -values set by Nvim runtime files (e.g. a ftplugin). In the latter case, -the default values are not restored when the LSP client is detached from -the buffer. - -- 'omnifunc' is set to |vim.lsp.omnifunc()|. This allows to trigger completion - using |i_CTRL-X_CTRL-O| + *lsp-defaults* +When the LSP client starts it enables diagnostics |vim.diagnostic| (see +|vim.diagnostic.config()| to customize). It also sets various default options, +listed below, if (1) the language server supports the functionality and (2) +the options are empty or were set by the builtin runtime (ftplugin) files. The +options are not restored when the LSP client is stopped or detached. + +- 'omnifunc' is set to |vim.lsp.omnifunc()|, use |i_CTRL-X_CTRL-O| to trigger + completion. - 'tagfunc' is set to |vim.lsp.tagfunc()|. This enables features like go-to-definition, |:tjump|, and keymaps like |CTRL-]|, |CTRL-W_]|, |CTRL-W_}| to utilize the language server. -- 'formatexpr' is set to |vim.lsp.formatexpr()| if both 'formatprg' and - 'formatexpr' are empty. This allows to format lines via |gq| if the language - server supports it. +- 'formatexpr' is set to |vim.lsp.formatexpr()|, so you can format lines via + |gq| if the language server supports it. + - To opt out of this use |gw| instead of gq, or set 'formatexpr' on LspAttach. -To use other LSP features like hover, rename, etc. you can setup some -additional keymaps. It's recommended to setup them in a |LspAttach| autocmd to -ensure they're only active if there is a LSP client running. An example: ->lua + *lsp-defaults-disable* +To override the above defaults, set or unset the options on |LspAttach|: >lua + vim.api.nvim_create_autocmd('LspAttach', { + callback = function(ev) + vim.bo[ev.buf].formatexpr = nil + vim.bo[ev.buf].omnifunc = nil + end, + }) + +To use other LSP features like hover, rename, etc. you can set other keymaps +on |LspAttach|. Example: >lua vim.api.nvim_create_autocmd('LspAttach', { callback = function(args) vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf }) end, }) -< -The most used functions are: +The most common functions are: - |vim.lsp.buf.hover()| - |vim.lsp.buf.format()| @@ -138,19 +140,6 @@ FAQ *lsp-faq* " (async = false is the default for format) autocmd BufWritePre *.rs lua vim.lsp.buf.format({ async = false }) < -- Q: How can I disable LSP formatting when using the |gq| command? - A: To use the default internal formatting method and bypass the LSP client's - 'formatexpr', use |gw| instead. - Alternatively you can completely disable LSP formatting with gq by - unsetting 'formatexpr': - ->lua - vim.api.nvim_create_autocmd('LspAttach', { - callback = function(args) - vim.bo[args.buf].formatexpr = nil - end, - }) -< *lsp-vs-treesitter* - Q: How do LSP and Treesitter compare? A: LSP requires a client and language server. The language server uses @@ -218,10 +207,10 @@ specification. These LSP requests/notifications are defined by default: *lsp-handler* -lsp-handlers are functions with special signatures that are designed to handle -responses and notifications from LSP servers. +LSP handlers are functions with signatures designed to handle LSP responses +and notifications. -For |lsp-request|, each |lsp-handler| has this signature: > +For |lsp-response|, each |lsp-handler| has this signature: > function(err, result, ctx, config) < @@ -374,42 +363,37 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method Handlers can be set by: - Setting a field in vim.lsp.handlers. *vim.lsp.handlers* - vim.lsp.handlers is a global table that contains the default mapping of - |lsp-method| names to |lsp-handlers|. - - To override the handler for the `"textDocument/definition"` method: >lua + vim.lsp.handlers is a global table that contains the default mapping of + |lsp-method| names to |lsp-handlers|. To override the handler for the + `"textDocument/definition"` method: >lua vim.lsp.handlers["textDocument/definition"] = my_custom_default_definition < -- The {handlers} parameter for |vim.lsp.start_client()|. - This will set the |lsp-handler| as the default handler for this server. - - For example: >lua +- The {handlers} parameter of |vim.lsp.start()|. This sets the default + |lsp-handler| for the server being started. Example: >lua - vim.lsp.start_client { + vim.lsp.start { ..., -- Other configuration omitted. handlers = { ["textDocument/definition"] = my_custom_server_definition }, } -- The {handler} parameter for |vim.lsp.buf_request()|. - This will set the |lsp-handler| ONLY for the current request. - - For example: >lua +- The {handler} parameter of |vim.lsp.buf_request_all()|. This sets + the |lsp-handler| ONLY for the given request(s). Example: >lua - vim.lsp.buf_request( + vim.lsp.buf_request_all( 0, "textDocument/definition", - definition_params, - my_request_custom_definition + my_request_params, + my_handler ) < In summary, the |lsp-handler| will be chosen based on the current |lsp-method| in the following order: -1. Handler passed to |vim.lsp.buf_request()|, if any. -2. Handler defined in |vim.lsp.start_client()|, if any. +1. Handler passed to |vim.lsp.buf_request_all()|, if any. +2. Handler defined in |vim.lsp.start()|, if any. 3. Handler defined in |vim.lsp.handlers|, if any. *vim.lsp.log_levels* @@ -478,6 +462,8 @@ LspReferenceText used for highlighting "text" references LspReferenceRead used for highlighting "read" references *hl-LspReferenceWrite* LspReferenceWrite used for highlighting "write" references + *hl-LspInlayHint* +LspInlayHint used for highlighting inlay hints *lsp-highlight-codelens* @@ -720,31 +706,27 @@ buf_notify({bufnr}, {method}, {params}) *vim.lsp.buf_notify()* (boolean) success true if any client returns true; false otherwise *vim.lsp.buf_request_all()* -buf_request_all({bufnr}, {method}, {params}, {callback}) - Sends an async request for all active clients attached to the buffer. - Executes the callback on the combined result. Parameters are the same as - |vim.lsp.buf_request()| but the return result and callback are different. +buf_request_all({bufnr}, {method}, {params}, {handler}) + Sends an async request for all active clients attached to the buffer and + executes the `handler` callback with the combined result. Parameters: ~ - • {bufnr} (integer) Buffer handle, or 0 for current. - • {method} (string) LSP method name - • {params} (table|nil) Parameters to send to the server - • {callback} (function) The callback to call when all requests are - finished. Unlike `buf_request`, this will collect all the - responses from each server instead of handling them. A map - of client_id:request_result will be provided to the - callback. + • {bufnr} (integer) Buffer handle, or 0 for current. + • {method} (string) LSP method name + • {params} (table|nil) Parameters to send to the server + • {handler} (function) Handler called after all requests are completed. + Server results are passed as a `client_id:result` map. Return: ~ - fun() cancel A function that will cancel all requests + fun() cancel Function that cancels all requests. *vim.lsp.buf_request_sync()* buf_request_sync({bufnr}, {method}, {params}, {timeout_ms}) Sends a request to all server and waits for the response of all of them. Calls |vim.lsp.buf_request_all()| but blocks Nvim while awaiting the - result. Parameters are the same as |vim.lsp.buf_request()| but the return - result is different. Wait maximum of {timeout_ms} (default 1000) ms. + result. Parameters are the same as |vim.lsp.buf_request_all()| but the + result is different. Waits a maximum of {timeout_ms} (default 1000) ms. Parameters: ~ • {bufnr} (integer) Buffer handle, or 0 for current. @@ -1316,6 +1298,13 @@ incoming_calls() *vim.lsp.buf.incoming_calls()* window. If the symbol can resolve to multiple items, the user can pick one in the |inputlist()|. +inlay_hint({bufnr}, {enable}) *vim.lsp.buf.inlay_hint()* + Enable/disable/toggle inlay hints for a buffer + + Parameters: ~ + • {bufnr} (integer) Buffer handle, or 0 for current + • {enable} (boolean|nil) true/false to enable/disable, nil to toggle + list_workspace_folders() *vim.lsp.buf.list_workspace_folders()* List workspace folders. |