From 56a4ef3c213d87bfba5f361376bd23eefdf6c6ec Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Fri, 11 Jul 2025 08:33:29 -0400
Subject: docs: lsp, ui events, dev guidance, osc7

fix #34981
---
 runtime/lua/vim/_core/server.lua     | 15 +++++++-------
 runtime/lua/vim/_meta/api.lua        |  4 ++++
 runtime/lua/vim/_meta/options.lua    |  5 +++--
 runtime/lua/vim/_meta/vimfn.lua      | 40 ++++++++++++++++++------------------
 runtime/lua/vim/_system.lua          |  4 ++++
 runtime/lua/vim/net.lua              | 16 +++++----------
 runtime/lua/vim/shared.lua           |  2 +-
 runtime/lua/vim/treesitter/query.lua |  5 ++---
 8 files changed, 47 insertions(+), 44 deletions(-)

(limited to 'runtime/lua/vim')

diff --git a/runtime/lua/vim/_core/server.lua b/runtime/lua/vim/_core/server.lua
index 281a5705ea..367dfe2ff3 100644
--- a/runtime/lua/vim/_core/server.lua
+++ b/runtime/lua/vim/_core/server.lua
@@ -1,17 +1,18 @@
 local M = {}
 
---- Called by builtin serverlist(). Returns all running servers.
---- in stdpath("run"). Does not include named pipes or TCP servers.
+--- Called by builtin serverlist(). Returns all running servers in stdpath("run").
+---
+--- - TODO: track TCP servers, somehow.
+--- - TODO: support Windows named pipes.
 ---
 --- @param listed string[] Already listed servers
---- @return string[] A list of currently running servers in stdpath("run")
+--- @return string[] # List of servers found on the current machine in stdpath("run").
 function M.serverlist(listed)
-  -- TODO: also get named pipes on Windows
   local socket_paths = vim.fs.find(function(name, _)
     return name:match('nvim.*')
   end, { path = vim.fn.stdpath('run'), type = 'socket', limit = math.huge })
 
-  local running_sockets = {}
+  local found = {} ---@type string[]
   for _, socket in ipairs(socket_paths) do
     -- Don't list servers twice
     if not vim.list_contains(listed, socket) then
@@ -20,14 +21,14 @@ function M.serverlist(listed)
         -- Check that the server is responding
         -- TODO: do we need a timeout or error handling here?
         if vim.fn.rpcrequest(chan, 'nvim_get_chan_info', 0).id then
-          table.insert(running_sockets, socket)
+          table.insert(found, socket)
         end
         vim.fn.chanclose(chan)
       end
     end
   end
 
-  return running_sockets
+  return found
 end
 
 return M
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 3177244e1a..26b51b7dbb 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -2045,6 +2045,10 @@ function vim.api.nvim_put(lines, type, after, follow) end
 --- Replaces terminal codes and `keycodes` ([<CR>], [<Esc>], ...) in a string with
 --- the internal representation.
 ---
+---
+--- Note:
+--- Lua can use |vim.keycode()| instead.
+---
 --- @see replace_termcodes
 --- @see cpoptions
 --- @param str string String to be converted.
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index 354e223cc8..ee87ebc322 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -2239,7 +2239,8 @@ vim.bo.et = vim.bo.expandtab
 --- Unset 'exrc' to stop further searching of 'exrc' files in parent
 --- directories, similar to `editorconfig.root`.
 ---
---- To get its own location, Lua exrc files can use `debug.getinfo()`.
+--- To get its own location, a Lua exrc file can use `debug.getinfo()`.
+--- See `lua-script-location`.
 ---
 --- Compare 'exrc' to `editorconfig`:
 --- - 'exrc' can execute any code; editorconfig only specifies settings.
@@ -2251,7 +2252,7 @@ vim.bo.et = vim.bo.expandtab
 --- 3. Create ".nvim.lua" in your project root directory with this line:
 ---
 --- ```lua
----      vim.cmd[[set runtimepath+=.nvim]]
+---     vim.cmd[[set runtimepath+=.nvim]]
 --- ```
 ---
 --- This option cannot be set from a `modeline` or in the `sandbox`, for
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 1674a52289..0c6d806a36 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -1855,35 +1855,35 @@ function vim.fn.exp(expr) end
 --- done like for the |cmdline-special| variables with their
 --- associated modifiers.  Here is a short overview:
 ---
----   %    current file name
----   #    alternate file name
----   #n    alternate file name n
----   <cfile>    file name under the cursor
----   <afile>    autocmd file name
----   <abuf>    autocmd buffer number (as a String!)
----   <amatch>  autocmd matched name
+---   %    Current file name
+---   #    Alternate file name
+---   #n    Alternate file name n
+---   <cfile>    File name under the cursor
+---   <afile>    Autocmd file name
+---   <abuf>    Autocmd buffer number (as a String!)
+---   <amatch>  Autocmd matched name
 ---   <cexpr>    C expression under the cursor
----   <sfile>    deprecated, use <script> or <stack>
----   <slnum>    sourced script line number or function
+---   <sfile>    Deprecated, use <script> or <stack>
+---   <slnum>    Sourced script line number or function
 ---       line number
----   <sflnum>  script file line number, also when in
+---   <sflnum>  Script file line number, also when in
 ---       a function
 ---   <SID>    "<SNR>123_"  where "123" is the
 ---       current script ID  |<SID>|
----   <script>  sourced script file, or script file
+---   <script>  Sourced script file, or script file
 ---       where the current function was defined.
----       Use |debug.getinfo()| in Lua scripts.
----   <stack>    call stack
----   <cword>    word under the cursor
+---       For Lua see |lua-script-location|.
+---   <stack>    Call stack
+---   <cword>    Word under the cursor
 ---   <cWORD>    WORD under the cursor
----   <client>  the {clientid} of the last received
+---   <client>  The {clientid} of the last received
 ---       message
 --- Modifiers:
----   :p    expand to full path
----   :h    head (last path component removed)
----   :t    tail (last path component only)
----   :r    root (one extension removed)
----   :e    extension only
+---   :p    Expand to full path
+---   :h    Head (last path component removed)
+---   :t    Tail (last path component only)
+---   :r    Root (one extension removed)
+---   :e    Extension only
 ---
 --- Example: >vim
 ---   let &tags = expand("%:p:h") .. "/tags"
diff --git a/runtime/lua/vim/_system.lua b/runtime/lua/vim/_system.lua
index 6e311823f0..06f0a8e102 100644
--- a/runtime/lua/vim/_system.lua
+++ b/runtime/lua/vim/_system.lua
@@ -471,6 +471,10 @@ end
 
 --- Runs a system command or throws an error if {cmd} cannot be run.
 ---
+--- The command runs directly (not in 'shell') so shell builtins such as "echo" in cmd.exe, cmdlets
+--- in powershell, or "help" in bash, will not work unless you actually invoke a shell:
+--- `vim.system({'bash', '-c', 'help'})`.
+---
 --- Examples:
 ---
 --- ```lua
diff --git a/runtime/lua/vim/net.lua b/runtime/lua/vim/net.lua
index 199b115e93..cd36e3027a 100644
--- a/runtime/lua/vim/net.lua
+++ b/runtime/lua/vim/net.lua
@@ -40,17 +40,11 @@ function M.request(url, opts, on_response)
   table.insert(args, url)
 
   local function on_exit(res)
-    local err_msg = nil
-    local response = nil
-
-    if res.code ~= 0 then
-      err_msg = (res.stderr ~= '' and res.stderr)
-        or string.format('Request failed with exit code %d', res.code)
-    else
-      response = {
-        body = opts.outpath and true or res.stdout,
-      }
-    end
+    local s = 'Request failed with exit code %d'
+    local err_msg = res.code ~= 0
+        and ((res.stderr ~= '' and res.stderr) or string.format(s, res.code))
+      or nil
+    local response = res.code == 0 and { body = opts.outpath and true or res.stdout } or nil
 
     if on_response then
       on_response(err_msg, response)
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index ccf7674253..9ce5d5b72d 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -1104,7 +1104,7 @@ do
         err_msg = is_valid(name, value, validator, msg, false)
       end
     elseif type(name) == 'table' then -- Form 2
-      vim.deprecate('vim.validate', 'vim.validate(name, value, validator, optional_or_msg)', '1.0')
+      vim.deprecate('vim.validate{<table>}', 'vim.validate(<params>)', '1.0')
       err_msg = validate_spec(name)
     else
       error('invalid arguments')
diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua
index a6964e985f..b93051b895 100644
--- a/runtime/lua/vim/treesitter/query.lua
+++ b/runtime/lua/vim/treesitter/query.lua
@@ -1163,9 +1163,8 @@ end
 
 --- Opens a live editor to query the buffer you started from.
 ---
---- Can also be shown with `:EditQuery`. [:EditQuery]()
----
---- `:EditQuery <tab>` completes the treesitter parser names in the runtime path.
+--- Can also be shown with the [:EditQuery]() command. `:EditQuery <tab>` completes available
+--- parsers.
 ---
 --- If you move the cursor to a capture name ("@foo"), text matching the capture is highlighted in
 --- the source buffer. The query editor is a scratch buffer, use `:write` to save it. You can find
-- 
cgit