commit 8001276bd01427722991398180d6d19b25d13978
parent 1d5b3b5b4c862524c9d910e36afc8df56492ec9d
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Fri, 13 Jun 2025 07:49:21 -0700
docs: vim.fs., diagnostics, lsp #34402
Diffstat:
10 files changed, 94 insertions(+), 114 deletions(-)
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
@@ -441,6 +441,7 @@ Use existing common {verb} names (actions) if possible:
- get: Gets things. Two variants (overloads):
1. `get<T>(id: int): T` returns one item.
2. `get<T>(filter: dict): T[]` returns a list.
+ - has: Checks for the presence of an item, feature, etc.
- inspect: Presents a high-level, often interactive, view
- is_enabled: Checks if functionality is enabled.
- open: Opens something (a buffer, window, …)
@@ -452,6 +453,7 @@ Use existing common {verb} names (actions) if possible:
- try_{verb}: Best-effort operation, failure returns null or error obj
Do NOT use these deprecated verbs:
+ - contains: Prefer "has".
- disable: Prefer `enable(enable: boolean)`.
- exit: Prefer "cancel" (or "stop" if appropriate).
- is_disabled: Prefer `is_enabled()`.
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
@@ -38,19 +38,6 @@ optionally supplied). A good rule of thumb is that if a method is meant to
modify the diagnostics for a buffer (e.g. |vim.diagnostic.set()|) then it
requires a namespace.
-==============================================================================
-DEFAULTS *diagnostic-defaults*
-
-These diagnostic keymaps are created unconditionally when Nvim starts:
-- |]d| is mapped in Normal mode to jump the next diagnostic in the current
- buffer
-- |[d| is mapped in Normal and Visual mode to jump to the previous diagnostic
- in th current buffer
-- |]D| is mapped in Normal mode to jump to the last diagnostic in the current buffer
-- |[D| is mapped in Normal mode to jump to the first diagnostic in the current
- buffer
-- <C-w>d is mapped in normal mode to show diagnostic under cursor.
-
*vim.diagnostic.severity* *diagnostic-severity*
The "severity" key in a diagnostic is one of the values defined in
`vim.diagnostic.severity`:
@@ -83,6 +70,16 @@ Functions that take a severity as an optional parameter (e.g.
This form allows users to filter for specific severities
==============================================================================
+DEFAULTS *diagnostic-defaults*
+
+These diagnostic keymaps are created unconditionally when Nvim starts:
+- `]d` jumps to the next diagnostic in the buffer. |]d-default|
+- `[d` jumps to the previous diagnostic in the buffer. |[d-default|
+- `]D` jumps to the last diagnostic in the buffer. |]D-default|
+- `[D` jumps to the first diagnostic in the buffer. |[D-default|
+- `<C-w>d` shows diagnostic at cursor in a floating window. |CTRL-W_d-default|
+
+==============================================================================
HANDLERS *diagnostic-handlers*
Diagnostics are shown to the user with |vim.diagnostic.show()|. The display of
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
@@ -717,7 +717,9 @@ Lua module: vim.lsp *lsp-core*
Fields: ~
• {cmd}? (`string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`)
- See `cmd` in |vim.lsp.ClientConfig|.
+ See `cmd` in |vim.lsp.ClientConfig|. See also
+ `reuse_client` to dynamically decide (per-buffer)
+ when `cmd` should be re-invoked.
• {filetypes}? (`string[]`) Filetypes the client will attach to, if
activated by `vim.lsp.enable()`. If not provided, the
client will attach to all filetypes.
@@ -1358,7 +1360,7 @@ Lua module: vim.lsp.client *lsp-client*
|vim.empty_dict()|, else it will be encoded
as an array.
• {cmd} (`string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`)
- command string[] that launches the language
+ 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
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
@@ -1468,20 +1468,21 @@ Lua module: vim *lua-vim*
vim.cmd({command}) *vim.cmd()*
Executes Vimscript (|Ex-commands|).
- Note that `vim.cmd` can be indexed with a command name to return a
- callable function to the command.
+ Can be indexed with a command name to get a function, thus you can write
+ `vim.cmd.echo(…)` instead of `vim.cmd{cmd='echo',…}`.
- Example: >lua
+ Examples: >lua
+ -- Single command:
vim.cmd('echo 42')
+ -- Multiline script:
vim.cmd([[
- augroup My_group
+ augroup my.group
autocmd!
autocmd FileType c setlocal cindent
augroup END
]])
- -- Ex command :echo "foo"
- -- Note string literals need to be double quoted.
+ -- Ex command :echo "foo". Note: string literals must be double-quoted.
vim.cmd('echo "foo"')
vim.cmd { cmd = 'echo', args = { '"foo"' } }
vim.cmd.echo({ args = { '"foo"' } })
@@ -1489,22 +1490,20 @@ vim.cmd({command}) *vim.cmd()*
-- Ex command :write! myfile.txt
vim.cmd('write! myfile.txt')
- vim.cmd { cmd = 'write', args = { "myfile.txt" }, bang = true }
- vim.cmd.write { args = { "myfile.txt" }, bang = true }
- vim.cmd.write { "myfile.txt", bang = true }
+ vim.cmd { cmd = 'write', args = { 'myfile.txt' }, bang = true }
+ vim.cmd.write { args = { 'myfile.txt' }, bang = true }
+ vim.cmd.write { 'myfile.txt', bang = true }
- -- Ex command :colorscheme blue
- vim.cmd('colorscheme blue')
- vim.cmd.colorscheme('blue')
+ -- Ex command :vertical resize +2
+ vim.cmd.resize({ '+2', mods = { vertical = true } })
<
Parameters: ~
- • {command} (`string|table`) Command(s) to execute. If a string,
- executes multiple lines of Vimscript at once. In this case,
- it is an alias to |nvim_exec2()|, where `opts.output` is
- set to false. Thus it works identical to |:source|. If a
- table, executes a single command. In this case, it is an
- alias to |nvim_cmd()| where `opts` is empty.
+ • {command} (`string|table`) Command(s) to execute.
+ • The string form supports multiline Vimscript (alias to
+ |nvim_exec2()|, behaves like |:source|).
+ • The table form executes a single command (alias to
+ |nvim_cmd()|).
See also: ~
• |ex-cmd-index|
@@ -3203,7 +3202,7 @@ vim.fs.root({source}, {marker}) *vim.fs.root()*
If the buffer is unnamed (has no backing file) or has a non-empty
'buftype' then the search begins from Nvim's |current-directory|.
- Example: >lua
+ Examples: >lua
-- Find the root of a Python project, starting from file 'main.py'
vim.fs.root(vim.fs.joinpath(vim.env.PWD, 'main.py'), {'pyproject.toml', 'setup.py' })
@@ -3228,21 +3227,12 @@ vim.fs.root({source}, {marker}) *vim.fs.root()*
file path (absolute or relative to the |current-directory|)
to begin the search from.
• {marker} (`(string|string[]|fun(name: string, path: string): boolean)[]|string|fun(name: string, path: string): boolean`)
- A marker or a list of markers. A marker has one of three
- types: string, a list of strings or a function. The
- parameter also accepts a list of markers, each of which is
- any of those three types. If a marker is a function, it is
- called for each evaluated item and should return true if
- {name} and {path} are a match. If a list of markers is
- passed, each marker in the list is evaluated in order and
- the first marker which is matched returns the parent
- directory that it found. This allows listing markers with
- priority. E.g. - in the following list, a parent directory
- containing either 'a' or 'b' is searched for. If neither is
- found, then 'c' is searched for. So, 'c' has lower priority
- than 'a' and 'b' which have equal priority. >lua
- marker = { { 'a', 'b' }, 'c' }
-<
+ Filename, function, or list thereof, that decides how to
+ find the root. To indicate "equal priority", specify items
+ in a nested list `{ { 'a.txt', 'b.lua' }, … }`. A function
+ item must return true if `name` and `path` are a match. Each
+ item (which may itself be a nested list) is evaluated
+ in-order against all ancestors, until a match is found.
Return: ~
(`string?`) Directory path containing one of the given markers, or nil
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
@@ -400,22 +400,23 @@ local VIM_CMD_ARG_MAX = 20
--- Executes Vimscript (|Ex-commands|).
---
---- Note that `vim.cmd` can be indexed with a command name to return a callable function to the
---- command.
+--- Can be indexed with a command name to get a function, thus you can write `vim.cmd.echo(…)`
+--- instead of `vim.cmd{cmd='echo',…}`.
---
---- Example:
+--- Examples:
---
--- ```lua
+--- -- Single command:
--- vim.cmd('echo 42')
+--- -- Multiline script:
--- vim.cmd([[
---- augroup My_group
+--- augroup my.group
--- autocmd!
--- autocmd FileType c setlocal cindent
--- augroup END
--- ]])
---
---- -- Ex command :echo "foo"
---- -- Note string literals need to be double quoted.
+--- -- Ex command :echo "foo". Note: string literals must be double-quoted.
--- vim.cmd('echo "foo"')
--- vim.cmd { cmd = 'echo', args = { '"foo"' } }
--- vim.cmd.echo({ args = { '"foo"' } })
@@ -423,22 +424,19 @@ local VIM_CMD_ARG_MAX = 20
---
--- -- Ex command :write! myfile.txt
--- vim.cmd('write! myfile.txt')
---- vim.cmd { cmd = 'write', args = { "myfile.txt" }, bang = true }
---- vim.cmd.write { args = { "myfile.txt" }, bang = true }
---- vim.cmd.write { "myfile.txt", bang = true }
+--- vim.cmd { cmd = 'write', args = { 'myfile.txt' }, bang = true }
+--- vim.cmd.write { args = { 'myfile.txt' }, bang = true }
+--- vim.cmd.write { 'myfile.txt', bang = true }
---
---- -- Ex command :colorscheme blue
---- vim.cmd('colorscheme blue')
---- vim.cmd.colorscheme('blue')
+--- -- Ex command :vertical resize +2
+--- vim.cmd.resize({ '+2', mods = { vertical = true } })
--- ```
---
---@diagnostic disable-next-line: undefined-doc-param
---@param command string|table Command(s) to execute.
---- If a string, executes multiple lines of Vimscript at once. In this
---- case, it is an alias to |nvim_exec2()|, where `opts.output` is set
---- to false. Thus it works identical to |:source|.
---- If a table, executes a single command. In this case, it is an alias
---- to |nvim_cmd()| where `opts` is empty.
+--- - The string form supports multiline Vimscript (alias to |nvim_exec2()|, behaves
+--- like |:source|).
+--- - The table form executes a single command (alias to |nvim_cmd()|).
---@see |ex-cmd-index|
vim.cmd = setmetatable({}, {
__call = function(_, command)
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
@@ -375,7 +375,7 @@ end
--- If the buffer is unnamed (has no backing file) or has a non-empty 'buftype' then the search
--- begins from Nvim's |current-directory|.
---
---- Example:
+--- Examples:
---
--- ```lua
--- -- Find the root of a Python project, starting from file 'main.py'
@@ -397,20 +397,12 @@ end
--- @since 12
--- @param source integer|string Buffer number (0 for current buffer) or file path (absolute or
--- relative to the |current-directory|) to begin the search from.
---- @param marker (string|string[]|fun(name: string, path: string): boolean)[]|string|fun(name: string, path: string): boolean A marker or a list of markers.
---- A marker has one of three types: string, a list of strings or a function. The
---- parameter also accepts a list of markers, each of which is any of those three
---- types. If a marker is a function, it is called for each evaluated item and
---- should return true if {name} and {path} are a match. If a list of markers is
---- passed, each marker in the list is evaluated in order and the first marker
---- which is matched returns the parent directory that it found. This allows
---- listing markers with priority. E.g. - in the following list, a parent directory
---- containing either 'a' or 'b' is searched for. If neither is found, then 'c' is
---- searched for. So, 'c' has lower priority than 'a' and 'b' which have equal
---- priority.
---- ```lua
---- marker = { { 'a', 'b' }, 'c' }
---- ```
+--- @param marker (string|string[]|fun(name: string, path: string): boolean)[]|string|fun(name: string, path: string): boolean
+--- Filename, function, or list thereof, that decides how to find the root. To
+--- indicate "equal priority", specify items in a nested list `{ { 'a.txt', 'b.lua' }, … }`.
+--- A function item must return true if `name` and `path` are a match. Each item
+--- (which may itself be a nested list) is evaluated in-order against all ancestors,
+--- until a match is found.
--- @return string? # Directory path containing one of the given markers, or nil if no directory was
--- found.
function M.root(source, marker)
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
@@ -272,6 +272,7 @@ end
--- @class vim.lsp.Config : vim.lsp.ClientConfig
---
--- See `cmd` in [vim.lsp.ClientConfig].
+--- See also `reuse_client` to dynamically decide (per-buffer) when `cmd` should be re-invoked.
--- @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
diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua
@@ -43,13 +43,12 @@ local validate = vim.validate
--- array.
--- @field capabilities? lsp.ClientCapabilities
---
---- 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 returns a table with member functions `request`, `notify`,
---- `is_closing` and `terminate`.
+--- 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 returns 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()|
+--- For TCP there is a builtin RPC client factory: |vim.lsp.rpc.connect()|
--- @field cmd string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient
---
--- Directory to launch the `cmd` process. Not related to `root_dir`.
diff --git a/src/nvim/ex_cmds_defs.h b/src/nvim/ex_cmds_defs.h
@@ -31,9 +31,8 @@
//
// All keys not described in the above table are reserved for future use.
//
-// 2. Add a "case: CMD_xxx" in the big switch in ex_docmd.c.
-// 3. Add an entry in the index for Ex commands at ":help ex-cmd-index".
-// 4. Add documentation in ../doc/xxx.txt. Add a tag for both the short and
+// 2. Add an entry in the index for Ex commands at ":help ex-cmd-index".
+// 3. Add documentation in ../doc/xxx.txt. Add a tag for both the short and
// long name of the command.
#define EX_RANGE 0x001u // allow a linespecs
diff --git a/test/functional/treesitter/parser_spec.lua b/test/functional/treesitter/parser_spec.lua
@@ -303,7 +303,7 @@ void ui_refresh(void)
}
}]]
- it('allows to iterate over nodes children', function()
+ it('can iterate over nodes children', function()
insert(test_text)
local res = exec_lua(function()
@@ -337,7 +337,7 @@ void ui_refresh(void)
exec_lua("vim.treesitter.get_parser(0, 'c')")
end)
- it('allows to get a child by field', function()
+ it('can get a child by field', function()
insert(test_text)
local res = exec_lua(function()
@@ -363,7 +363,7 @@ void ui_refresh(void)
assert(res_fail)
end)
- it('supports getting text of multiline node', function()
+ it('can get text of multiline node', function()
insert(test_text)
local res = exec_lua(function()
local parser = vim.treesitter.get_parser(0, 'c')
@@ -380,7 +380,7 @@ void ui_refresh(void)
eq('void', res2)
end)
- it('supports getting text where start of node is one past EOF', function()
+ it('can get text where start of node is one past EOF', function()
local text = [[
def run
a = <<~E
@@ -407,7 +407,7 @@ end]]
)
end)
- it('supports getting empty text if node range is zero width', function()
+ it('can get empty text if node range is zero-width', function()
local text = [[
```lua
{}
@@ -429,7 +429,7 @@ end]]
eq(true, result)
end)
- it('allows to set simple ranges', function()
+ it('can set simple ranges', function()
insert(test_text)
local res = exec_lua(function()
@@ -461,7 +461,7 @@ end]]
eq({ { { 0, 0, 0, 17, 1, 508 } } }, range_tbl)
end)
- it('allows to set complex ranges', function()
+ it('can set complex ranges', function()
insert(test_text)
local res = exec_lua(function()
@@ -495,7 +495,7 @@ end]]
}, res)
end)
- it('allows to create string parsers', function()
+ it('can create string parsers', function()
local ret = exec_lua(function()
local parser = vim.treesitter.get_string_parser('int foo = 42;', 'c')
return { parser:parse()[1]:root():range() }
@@ -513,7 +513,7 @@ end]]
eq({ 0, 0, 0, 13 }, ret)
end)
- it('allows to run queries with string parsers', function()
+ it('can run queries with string parsers', function()
local txt = [[
int foo = 42;
int bar = 13;
@@ -535,7 +535,7 @@ end]]
eq({ { 0, 10, 0, 13 } }, ret)
end)
- describe('when creating a language tree', function()
+ describe('creating a language tree', function()
local function get_ranges()
return exec_lua(function()
local result = {}
@@ -557,8 +557,8 @@ int x = INT_MAX;
]])
end)
- describe('when parsing regions independently', function()
- it('should inject a language', function()
+ describe('parsing regions independently', function()
+ it('injects a language', function()
exec_lua(function()
_G.parser = vim.treesitter.get_parser(0, 'c', {
injections = {
@@ -596,7 +596,7 @@ int x = INT_MAX;
end)
describe('when parsing regions combined', function()
- it('should inject a language', function()
+ it('injects a language', function()
exec_lua(function()
_G.parser = vim.treesitter.get_parser(0, 'c', {
injections = {
@@ -777,7 +777,7 @@ int x = INT_MAX;
end)
describe('when using injection.self', function()
- it('should inject the source language', function()
+ it('injects the source language', function()
exec_lua(function()
_G.parser = vim.treesitter.get_parser(0, 'c', {
injections = {
@@ -815,7 +815,7 @@ int x = INT_MAX;
end)
describe('when using the offset directive', function()
- it('should shift the range by the directive amount', function()
+ it('shifts the range by the directive amount', function()
exec_lua(function()
_G.parser = vim.treesitter.get_parser(0, 'c', {
injections = {
@@ -838,7 +838,7 @@ int x = INT_MAX;
{ 5, 17, 5, 17 }, -- VALUE2 123
}, get_ranges())
end)
- it('should apply offsets to quantified captures', function()
+ it('applies offsets to quantified captures', function()
local function get_ltree_ranges()
return exec_lua(function()
local result = {}
@@ -870,7 +870,7 @@ int x = INT_MAX;
},
}, get_ltree_ranges())
end)
- it('should list all directives', function()
+ it('lists all directives', function()
local res_list = exec_lua(function()
local query = vim.treesitter.query
@@ -886,7 +886,7 @@ int x = INT_MAX;
end)
end)
- it('properly clips nested injections #34098', function()
+ it('clips nested injections #34098', function()
insert([=[
```lua
vim.cmd([[
@@ -923,7 +923,7 @@ int x = INT_MAX;
]])
end)
- it('should return the correct language tree', function()
+ it('returns the correct language tree', function()
local result = exec_lua(function()
local parser = vim.treesitter.get_parser(0, 'c', {
injections = {
@@ -973,7 +973,7 @@ print()
describe('when getting/setting match data', function()
describe('when setting for the whole match', function()
- it('should set/get the data correctly', function()
+ it('sets/gets the data correctly', function()
insert([[
int x = 3;
]])
@@ -991,7 +991,7 @@ print()
end)
describe('when setting a key on a capture', function()
- it('it should create the nested table', function()
+ it('creates the nested table', function()
insert([[
int x = 3;
]])
@@ -1011,7 +1011,7 @@ print()
eq('value', result)
end)
- it('it should not overwrite the nested table', function()
+ it('does not overwrite the nested table', function()
insert([[
int x = 3;
]])
@@ -1267,7 +1267,7 @@ print()
eq({ { { 1, 0, 21, 2, 0, 42 } } }, exec_lua('return parser2:children().lua:included_regions()'))
end)
- it('parsers injections incrementally', function()
+ it('parses injections incrementally', function()
insert(dedent [[
>lua
local a = {}
@@ -1410,7 +1410,7 @@ print()
end)
it(
- 'is valid excluding, invalid including children after a range parse that does not lead to parsing not parsed injections',
+ 'is valid excluding, invalid including children after a range parse that does not lead to parsing non-parsed injections',
function()
exec_lua('vim.treesitter.get_parser():parse({2, 4})')
eq(true, exec_lua('return vim.treesitter.get_parser():is_valid(true)'))
