Repository: neovim/neovim
File: runtime/lua/vim/lsp.lua (Lua)

Code before:

  --- @diagnostic disable-next-line: invisible
  table.insert(client._on_exit_cbs, on_client_exit)

  all_clients[client.id] = client

  client:initialize()

  return client.id, nil
end

--- @class vim.lsp.Config : vim.lsp.ClientConfig
---
--- See `cmd` in [vim.lsp.ClientConfig].
--- @field cmd? string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient
---
--- Filetypes the client will attach to, if activated by `vim.lsp.enable()`.
--- If not provided, then the client will attach to all filetypes.
--- @field filetypes? string[]
---
--- Directory markers (.e.g. '.git/') where the LSP server will base its workspaceFolders,
--- rootUri, and rootPath on initialization. Unused if `root_dir` is provided.
---
--- It's possibile to specify marker's priority. The default behaviour performs a
--- directory-up first search, but it can be configured to look for multple markers in each
--- directory before going up.
---
--- Example (default, directory-up first):
---
--- ```lua
---   root_markers = { 'stylua.toml', '.git' }
--- ```
---
--- Looks for `stylua.toml` in every directory going up, if it isn't found it does
--- the same for `.git`.
---
--- Example (mixed priorities):
---
--- ```lua
---   root_markers = { { 'stylua.toml', '.luarc.json' }, '.git' }
--- ```
---
--- Looks for both `.stylua.toml` and `.luarc.json` (in this order) in every
--- directory going up, if none of them is found it does the same for `.git`.
--- @field root_markers? (string|string[])[]
---
--- Directory where the LSP server will base its workspaceFolders, rootUri, and
--- rootPath on initialization. If a function, it is passed the buffer number
--- and a callback argument which must be called with the value of root_dir to
--- use. The LSP server will not be started until the callback is called.
--- @field root_dir? string|fun(bufnr: integer, cb:fun(root_dir?:string))

Review comment (suggestion):
We aren't specifying a marker's priority, we're allowing different markers to be ordered by priority. Maybe this is splitting hairs a bit, but when I read "specify a marker's priority" I'm expecting to see some kind of map where each marker can be assigned an arbitrary number, which isn't what this API provides.

```suggestion
--- Each entry in this list is a set of one or more markers. For each set, Nvim
--- will search upwards for each marker contained in the set. If a marker is
--- found, the directory which contains that marker is used as the root
--- directory. If no markers from the set are found, the process is repeated
--- with the next set in the list.
```

Code after:
  local client = assert(res)

  --- @diagnostic disable-next-line: invisible
  table.insert(client._on_exit_cbs, on_client_exit)

  all_clients[client.id] = client

  client:initialize()

  return client.id, nil
end

--- @class vim.lsp.Config : vim.lsp.ClientConfig
---
--- See `cmd` in [vim.lsp.ClientConfig].
--- @field cmd? string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient
---
--- Filetypes the client will attach to, if activated by `vim.lsp.enable()`. If not provided, the
--- client will attach to all filetypes.
--- @field filetypes? string[]
---
--- Predicate which decides if a client should be re-used. Used on all running clients. The default
--- implementation re-uses a client if name and root_dir matches.
--- @field reuse_client? fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): boolean
---
--- [lsp-root_dir()]() Directory where the LSP server will base its workspaceFolders, rootUri, and
--- rootPath on initialization. The function form receives a buffer number and `on_dir` callback
--- which it must call to provide root_dir, or LSP will not be activated for the buffer. Thus
--- a `root_dir()` function can dynamically decide per-buffer whether to activate (or skip) LSP. See
--- example at |vim.lsp.enable()|.
--- @field root_dir? string|fun(bufnr: integer, on_dir:fun(root_dir?:string))
---
--- Directory markers (.e.g. '.git/') where the LSP server will base its workspaceFolders,
--- rootUri, and rootPath on initialization. Unused if `root_dir` is provided.
---
--- The list order decides the priority. To indicate "equal priority", specify names in a nested list (`{ { 'a', 'b' }, ... }`)
--- Each entry in this list is a set of one or more markers. For each set, Nvim
--- will search upwards for each marker contained in the set. If a marker is
--- found, the directory which contains that marker is used as the root
--- directory. If no markers from the set are found, the process is repeated
--- with the next set in the list.
---
--- Example:
---
--- ```lua
---   root_markers = { 'stylua.toml', '.git' }
--- ```
---
--- Find the first parent directory containing the file `stylua.toml`. If not
--- found, find the first parent directory containing the file or directory
--- `.git`.