docs: lsp, options, api #38980

docs: lsp, options

- revert bogus change to `_meta/builtin_types.lua` from 3a4a66017b

Close #38991

Co-authored-by: David Mejorado <david.mejorado@gmail.com>

runtime/lua/vim/_meta/api.gen.lua

@@ -2204,14 +2204,10 @@ function vim.api.nvim_set_current_win(window) end
 ---   ```
 function vim.api.nvim_set_decoration_provider(ns_id, opts) end
 
---- Sets a highlight group.
+--- Sets a highlight group. By default, replaces the entire definition (e.g. `nvim_set_hl(0, 'Visual', {})`
+--- will clear the "Visual" group), unless `update` is specified.
 ---
 --- Note:
---- Unlike the `:highlight` command which can update a highlight group,
---- this function completely replaces the definition. For example:
---- `nvim_set_hl(0, 'Visual', {})` will clear the highlight group
---- 'Visual'.
----
 --- The fg and bg keys also accept the string values `"fg"` or `"bg"`
 --- which act as aliases to the corresponding foreground and background
 --- values of the Normal group. If the Normal group has not been defined,
@@ -2240,17 +2236,17 @@ function vim.api.nvim_set_decoration_provider(ns_id, opts) end
 --- - ctermfg: Sets foreground of cterm color `ctermfg`
 --- - default: boolean Don't override existing definition `:hi-default`
 --- - dim: boolean
---- - fg: color name or "#RRGGBB", see note.
+--- - fg: Color name or "#RRGGBB", see note.
 --- - fg_indexed: boolean (default false) If true, fg is a terminal palette index (0-255).
 --- - font: GUI font name (string). Sets `highlight-font`. Use "NONE" to clear.
---- - force: if true force update the highlight group when it exists.
+--- - force: boolean (default false) Update the highlight group even if it already exists.
 --- - italic: boolean
 --- - link: Name of highlight group to link to. `:hi-link`
---- - link_global: Like "link", but always resolved in the global (ns=0) namespace.
+--- - link_global: Like "link", but always resolved in the global namespace (ns=0).
 --- - nocombine: boolean
 --- - overline: boolean
 --- - reverse: boolean
---- - sp: color name or "#RRGGBB"
+--- - sp: Color name or "#RRGGBB"
 --- - standout: boolean
 --- - strikethrough: boolean
 --- - undercurl: boolean

runtime/lua/vim/_meta/builtin_types.lua

@@ -201,7 +201,7 @@ error('Cannot require a meta file')
 --- @field priority? integer
 
 --- @class vim.fn.sign_placelist.list.item
---- @field buf integer|string
+--- @field buffer integer|string
 --- @field group? string
 --- @field id? integer
 --- @field lnum? integer|string
@@ -209,11 +209,11 @@ error('Cannot require a meta file')
 --- @field priority? integer
 
 --- @class vim.fn.sign_unplace.dict
---- @field buf? integer|string
+--- @field buffer? integer|string
 --- @field id? integer
 
 --- @class vim.fn.sign_unplacelist.list.item
---- @field buf? integer|string
+--- @field buffer? integer|string
 --- @field group? string
 --- @field id? integer
 

runtime/lua/vim/_meta/options.gen.lua

@@ -1181,8 +1181,7 @@ vim.go.cia = vim.go.completeitemalign
 --- 	    "menu" or "menuone". No effect if "longest" is present.
 ---
 ---    noselect Same as "noinsert", except that no menu item is
---- 	    pre-selected.  If both "noinsert" and "noselect" are
---- 	    present, "noselect" takes precedence.  This is enabled
+--- 	    pre-selected.  Takes precedence over "noinsert". Enabled
 --- 	    automatically when 'autocomplete' is on, unless
 --- 	    "preinsert" is also enabled.
 ---
@@ -1204,14 +1203,13 @@ vim.go.cia = vim.go.completeitemalign
 --- 	    'ignorecase' is set without 'infercase'.
 --- 	    See also `preinserted()`.
 ---
+---    preselect   Selects the first completion item whose "preselect"
+--- 	    field is set, if any. Takes precedence over "noselect".
+---
 ---    preview  Show extra information about the currently selected
 --- 	    completion in the preview window.  Only works in
 --- 	    combination with "menu" or "menuone".
 ---
----     preselect   Select the completion item that has the "preselect"
---- 	    attribute set. If both "noselect" and "preselect" are present,
---- 	    "preselect" takes precedence.
----
 --- Only "fuzzy", "longest", "popup", "preinsert", "preselect" and
 --- "preview" have an effect when 'autocomplete' is enabled.
 ---
@@ -2960,15 +2958,15 @@ vim.o.fo = vim.o.formatoptions
 vim.bo.formatoptions = vim.o.formatoptions
 vim.bo.fo = vim.bo.formatoptions
 
---- The name of an external program that will be used to format the lines
---- selected with the `gq` operator.  The program must take the input on
---- stdin and produce the output on stdout.  The Unix program "fmt" is
---- such a program.
---- If the 'formatexpr' option is not empty it will be used instead.
---- Otherwise, if 'formatprg' option is an empty string, the internal
---- format function will be used `C-indenting`.
---- Environment variables are expanded `:set_env`.  See `option-backslash`
---- about including spaces and backslashes.
+--- External program used to format lines with `gq`. Ignored if
+--- 'formatexpr' is set.
+---
+--- If empty, the internal `C-indenting` function will be used.
+---
+--- The program must take input on stdin and produce output on stdout. The
+--- Unix program "fmt" is such a program. Environment variables are
+--- expanded `:set_env`.  See `option-backslash` about including spaces
+--- and backslashes.
 ---
 --- @type string
 vim.o.formatprg = ""

runtime/lua/vim/lsp.lua

@@ -702,7 +702,7 @@ end
 --- See |vim.lsp.ClientConfig| for all available options. The most important are:
 ---
 --- - `name` arbitrary name for the LSP client. Should be unique per language server.
---- - `cmd` command string[] or function.
+--- - `cmd` command string[] or function. See also |lsp-server|.
 --- - `root_dir` path to the project root. By default this is used to decide if an existing client
 ---   should be re-used. The example above uses |vim.fs.root()| to detect the root by traversing
 ---   the file system upwards starting from the current directory until either a `pyproject.toml`

runtime/lua/vim/lsp/_changetracking.lua

@@ -165,9 +165,12 @@ function M.init(client, bufnr)
   end
 end
 
+--- Sends didOpen/didClose/didSave to all client groups.
+---
 --- @param bufnr integer
 function M._send_did_save(bufnr)
   local groups = {} ---@type table<string,vim.lsp.CTGroup>
+  -- Collect all client groups.
   for _, client in pairs(vim.lsp.get_clients({ bufnr = bufnr })) do
     local group = get_group(client)
     groups[group_key(group)] = group
@@ -176,6 +179,7 @@ function M._send_did_save(bufnr)
   local uri = vim.uri_from_bufnr(bufnr)
   local text = vim.func._memoize('concat', vim.lsp._buf_get_full_text)
 
+  -- Send didOpen/didClose/didSave to all client groups.
   for _, group in pairs(groups) do
     local name = api.nvim_buf_get_name(bufnr)
     local state = state_by_group[group]

runtime/lua/vim/lsp/client.lua

@@ -51,10 +51,10 @@ local all_clients = {}
 ---
 --- Command `string[]` that launches the language server (treated as in |jobstart()|, must be
 --- absolute or on `$PATH`, shell constructs like "~" are not expanded), or function that creates an
---- RPC client. Function receives a `dispatchers` table and the resolved `config`, and must return
---- a table with member functions `request`, `notify`, `is_closing` and `terminate`.
---- See |vim.lsp.rpc.request()|, |vim.lsp.rpc.notify()|.
---- For TCP there is a builtin RPC client factory: |vim.lsp.rpc.connect()|
+--- RPC client (or an in-process |lsp-server|). Function receives a `dispatchers` table and the
+--- resolved `config`, and must return an object in the form of |vim.lsp.rpc.Client|.
+--- - See |vim.lsp.rpc.request()| |vim.lsp.rpc.notify()|
+--- - For TCP there is a builtin RPC client factory: |vim.lsp.rpc.connect()|
 --- @field cmd string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers, config: vim.lsp.ClientConfig): vim.lsp.rpc.Client
 ---
 --- Directory to launch the `cmd` process. Not related to `root_dir`.

runtime/lua/vim/lsp/util.lua

@@ -1050,11 +1050,7 @@ function M.show_document(location, position_encoding, opts)
     if vim.api.nvim_get_mode().mode == 'i' then
       local line = api.nvim_buf_get_lines(bufnr, row, row + 1, false)[1] or ''
       if col >= #line then
-        vim.api.nvim_feedkeys(
-          vim.api.nvim_replace_termcodes('<End>', true, false, true),
-          'n',
-          false
-        )
+        vim.api.nvim_feedkeys(vim.keycode('<End>'), 'n', false)
       end
     end
   end