docs: vim.fs., diagnostics, lsp #34402

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()`.

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`:
@@ -82,6 +69,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*
 

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

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
+    Can be indexed with a command name to get a function, thus you can write
-    callable function to the command.
+    `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"
+        -- Ex command :echo "foo". Note: string literals must be double-quoted.
-        -- Note string literals need to 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 { cmd = 'write', args = { 'myfile.txt' }, bang = true }
-        vim.cmd.write { args = { "myfile.txt" }, bang = true }
+        vim.cmd.write { args = { 'myfile.txt' }, bang = true }
-        vim.cmd.write { "myfile.txt", bang = true }
+        vim.cmd.write { 'myfile.txt', bang = true }
 
-        -- Ex command :colorscheme blue
+        -- Ex command :vertical resize +2
-        vim.cmd('colorscheme blue')
+        vim.cmd.resize({ '+2', mods = { vertical = true } })
-        vim.cmd.colorscheme('blue')
 <
 
     Parameters: ~
-      • {command}  (`string|table`) Command(s) to execute. If a string,
+      • {command}  (`string|table`) Command(s) to execute.
-                   executes multiple lines of Vimscript at once. In this case,
+                   • The string form supports multiline Vimscript (alias to
-                   it is an alias to |nvim_exec2()|, where `opts.output` is
+                     |nvim_exec2()|, behaves like |:source|).
-                   set to false. Thus it works identical to |:source|. If a
+                   • The table form executes a single command (alias to
-                   table, executes a single command. In this case, it is an
+                     |nvim_cmd()|).
-                   alias to |nvim_cmd()| where `opts` is empty.
 
     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
+                  Filename, function, or list thereof, that decides how to
-                  types: string, a list of strings or a function. The
+                  find the root. To indicate "equal priority", specify items
-                  parameter also accepts a list of markers, each of which is
+                  in a nested list `{ { 'a.txt', 'b.lua' }, … }`. A function
-                  any of those three types. If a marker is a function, it is
+                  item must return true if `name` and `path` are a match. Each
-                  called for each evaluated item and should return true if
+                  item (which may itself be a nested list) is evaluated
-                  {name} and {path} are a match. If a list of markers is
+                  in-order against all ancestors, until a match is found.
-                  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' }
-<
 
     Return: ~
         (`string?`) Directory path containing one of the given markers, or nil

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
+--- Can be indexed with a command name to get a function, thus you can write `vim.cmd.echo(…)`
---- command.
+--- 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"
+--- -- Ex command :echo "foo". Note: string literals must be double-quoted.
---- -- Note string literals need to 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 { cmd = 'write', args = { 'myfile.txt' }, bang = true }
---- vim.cmd.write { args = { "myfile.txt" }, bang = true }
+--- vim.cmd.write { args = { 'myfile.txt' }, bang = true }
---- vim.cmd.write { "myfile.txt", bang = true }
+--- vim.cmd.write { 'myfile.txt', bang = true }
 ---
---- -- Ex command :colorscheme blue
+--- -- Ex command :vertical resize +2
---- vim.cmd('colorscheme blue')
+--- vim.cmd.resize({ '+2', mods = { vertical = true } })
---- vim.cmd.colorscheme('blue')
 --- ```
 ---
 ---@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
+---       - The string form supports multiline Vimscript (alias to |nvim_exec2()|, behaves
----                            case, it is an alias to |nvim_exec2()|, where `opts.output` is set
+---         like |:source|).
----                            to false. Thus it works identical to |:source|.
+---       - The table form executes a single command (alias to |nvim_cmd()|).
----                            If a table, executes a single command. In this case, it is an alias
----                            to |nvim_cmd()| where `opts` is empty.
 ---@see |ex-cmd-index|
 vim.cmd = setmetatable({}, {
   __call = function(_, command)

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.
+--- @param marker (string|string[]|fun(name: string, path: string): boolean)[]|string|fun(name: string, path: string): boolean
----               A marker has one of three types: string, a list of strings or a function. The
+---               Filename, function, or list thereof, that decides how to find the root. To
----               parameter also accepts a list of markers, each of which is any of those three
+---               indicate "equal priority", specify items in a nested list `{ { 'a.txt', 'b.lua' }, … }`.
----               types. If a marker is a function, it is called for each evaluated item and
+---               A function item must return true if `name` and `path` are a match. Each item
----               should return true if {name} and {path} are a match. If a list of markers is
+---               (which may itself be a nested list) is evaluated in-order against all ancestors,
----               passed, each marker in the list is evaluated in order and the first marker
+---               until a match is found.
----               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' }
----               ```
 --- @return string? # Directory path containing one of the given markers, or nil if no directory was
 ---                   found.
 function M.root(source, marker)

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

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
+--- Command `string[]` that launches the language server (treated as in |jobstart()|, must be
---- server (treated as in |jobstart()|, must be absolute or on `$PATH`, shell constructs like
+--- absolute or on `$PATH`, shell constructs like "~" are not expanded), or function that creates an
---- "~" are not expanded), or function that creates an RPC client. Function receives
+--- RPC client. Function receives a `dispatchers` table and returns a table with member functions
---- a `dispatchers` table and returns a table with member functions `request`, `notify`,
+--- `request`, `notify`, `is_closing` and `terminate`.
---- `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`.

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.
+// 2. Add an entry in the index for Ex commands at ":help ex-cmd-index".
-// 3. 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
-// 4. 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

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()
+    describe('parsing regions independently', function()
-      it('should inject a language', 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)'))