docs: misc

Close #37458
Close #37838
Close #37840
Close #37872
Close #37890
Close #38016
Close #38051
Close #38189
Close #38225
Close #38243
Close #38250

Co-authored-by: Colin Kennedy <colinvfx@gmail.com>
Co-authored-by: "Mike J. McGuirk" <mike.j.mcguirk@gmail.com>
Co-authored-by: Austin Rambo <ramboaustin13@gmail.com>
Co-authored-by: Jonathan Birk <1965620+cafce25@users.noreply.github.com>
Co-authored-by: Sean Dewar <6256228+seandewar@users.noreply.github.com>
Co-authored-by: Mike Smith <10135646+mikesmithgh@users.noreply.github.com>
Co-authored-by: Saad Nadeem <saadndm.sn@gmail.com>
Co-authored-by: brianhuster <phambinhanctb2004@gmail.com>
Co-authored-by: zeertzjq <zeertzjq@outlook.com>
Co-authored-by: Yi Ming <ofseed@foxmail.com>

runtime/doc/cmdline.txt

@@ -124,7 +124,7 @@ CTRL-W		Delete the |word| before the cursor.  This depends on the
 		'iskeyword' option.
 							*c_CTRL-U*
 CTRL-U		Remove all characters between the cursor position and
-		the beginning of the line.  Previous versions of vim
+		the beginning of the line.  Previous versions of Vim
 		deleted all characters on the line.  If that is the
 		preferred behavior, add the following to your vimrc: >
 			:cnoremap <C-U> <C-E><C-U>

runtime/doc/faq.txt

@@ -356,7 +356,7 @@ CALLING INPUTLIST(), ECHOMSG, ... IN FILETYPE PLUGINS AND AUTOCMD DOES NOT WORK
 - https://github.com/vim/vim/issues/4379
 
 This is because Nvim sets `shortmess+=F` by default. Vim behaves the same way
-with `set shortmes+=F`. There are plans to improve this, but meanwhile as a
+with `set shortmess+=F`. There are plans to improve this, but meanwhile as a
 workaround, use `set shortmess-=F` or use `unsilent` as follows.
 >vim
     unsilent let var = inputlist(['1. item1', '2. item2'])
@@ -386,7 +386,7 @@ Or, if you want automatic reloading when assigning to |g:clipboard|, set
       runtime autoload/provider/clipboard.vim
     endfunction
 
-    if !exists('s:loaded")
+    if !exists('s:loaded')
       call dictwatcheradd(g:, 'clipboard', function('s:clipboard_changed'))
     endif
     let s:loaded = v:true

runtime/doc/index.txt

@@ -1057,7 +1057,8 @@ Tag		Command		Command-line editing-mode action	~
 				under the cursor literally
 		CTRL-S		not used, or used for terminal control flow
 |c_CTRL-T|	CTRL-T		previous match when 'incsearch' is active
-|c_CTRL-U|	CTRL-U		remove all characters
+|c_CTRL-U|	CTRL-U		remove all characters between the cursor
+				and beginning of command-line
 |c_CTRL-V|	CTRL-V		insert next non-digit literally, insert three
 				digit decimal number as a single byte.
 |c_CTRL-W|	CTRL-W		delete the word in front of the cursor

runtime/doc/quickref.txt

@@ -1045,7 +1045,8 @@ Short explanation of each option:		*option-list*
 |c_<BS>|	<BS>		   delete the character in front of the cursor
 |c_<Del>|	<Del>		   delete the character under the cursor
 |c_CTRL-W|	CTRL-W		   delete the word in front of the cursor
-|c_CTRL-U|	CTRL-U		   remove all characters
+|c_CTRL-U|	CTRL-U		   remove all characters between the cursor
+				      and beginning of command-line
 
 |c_<Up>|	<Up>/<Down>	   recall older/newer command-line that starts
 				      with current command

runtime/doc/vim_diff.txt

@@ -755,6 +755,8 @@ Eval:
 - *err_teapot()*
 - *js_encode()*
 - *js_decode()*
+- *listener_add()* , etc: use |api-buffer-updates-lua| instead.
+- *redraw_listener_add()* , etc:  use |nvim_set_decoration_provider()| instead.
 - *v:none* (used by Vim to represent JavaScript "undefined"); use |v:null| instead.
 - *v:sizeofint*
 - *v:sizeoflong*

runtime/doc/vimfn.txt

@@ -7851,7 +7851,7 @@ readdir({directory} [, {expr}])                                      *readdir()*
 
                 Parameters: ~
                   • {directory} (`string`)
-                  • {expr} (`integer?`)
+                  • {expr} (`integer|string|fun(name: string): integer?`)
 
                 Return: ~
                   (`any`)
@@ -8266,7 +8266,7 @@ screencol()                                                        *screencol()*
 <
 
                 Return: ~
-                  (`integer[]`)
+                  (`integer`)
 
 screenpos({winid}, {lnum}, {col})                                  *screenpos()*
 		The result is a Dict with the screen position of the text
@@ -8298,7 +8298,7 @@ screenpos({winid}, {lnum}, {col})                                  *screenpos()*
                   • {col} (`integer`)
 
                 Return: ~
-                  (`any`)
+                  (`{ col: integer, curscol: integer, endcol: integer, row: integer }`)
 
 screenrow()                                                        *screenrow()*
 		The result is a Number, which is the current screen row of the
@@ -8742,7 +8742,7 @@ searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
                   • {skip} (`string|function?`)
 
                 Return: ~
-                  (`any`)
+                  (`{ [1]: integer, [2]: integer, [3]: integer? }`)
 
 serverlist([{opts}])                                              *serverlist()*
 		Returns a list of server addresses, or empty if all servers

runtime/lua/vim/_meta.lua

@@ -20,6 +20,7 @@ vim.iter = require('vim.iter')
 vim.keymap = require('vim.keymap')
 vim.loader = require('vim.loader')
 vim.lsp = require('vim.lsp')
+vim.net = require('vim.net')
 vim.pack = require('vim.pack')
 vim.pos = require('vim.pos')
 vim.range = require('vim.range')

runtime/lua/vim/_meta/api.lua

@@ -1299,15 +1299,15 @@ function vim.api.nvim_get_autocmds(opts) end
 ---      - "stderr"     stderr of this Nvim instance
 ---      - "socket"     TCP/IP socket or named pipe
 ---      - "job"        Job with communication over its stdio.
---- -  "mode"    How data received on the channel is interpreted.
+--- - "mode"     How data received on the channel is interpreted.
 ---      - "bytes"      Send and receive raw bytes.
 ---      - "terminal"   |terminal| instance interprets ASCII sequences.
 ---      - "rpc"        |RPC| communication on the channel is active.
---- -  "pty"     (optional) Name of pseudoterminal. On a POSIX system this is a device path like
+--- - "pty"      (optional) Name of pseudoterminal. On a POSIX system this is a device path like
 ---              "/dev/pts/1". If unknown, the key will still be present if a pty is used (e.g.
 ---              for conpty on Windows).
---- -  "buffer"  (optional) Buffer connected to |terminal| instance.
---- -  "client"  (optional) Info about the peer (client on the other end of the channel), as set
+--- - "buffer"   (optional) Buffer connected to |terminal| instance.
+--- - "client"   (optional) Info about the peer (client on the other end of the channel), as set
 ---              by |nvim_set_client_info()|.
 --- - "exitcode" (optional) Exit code of the |terminal| process.
 ---

runtime/lua/vim/_meta/builtin_types.lua

@@ -60,6 +60,7 @@
 --- @field botline integer
 --- @field bufnr integer
 --- @field height integer
+--- @field leftcol integer
 --- @field loclist integer
 --- @field quickfix integer
 --- @field tabnr integer

runtime/lua/vim/_meta/vimfn.lua

@@ -7132,7 +7132,7 @@ function vim.fn.readblob(fname, offset, size) end
 --- Returns an empty List on error.
 ---
 --- @param directory string
---- @param expr? integer
+--- @param expr? integer|string|fun(name: string): integer
 --- @return any
 function vim.fn.readdir(directory, expr) end
 
@@ -7521,7 +7521,7 @@ function vim.fn.screenchars(row, col) end
 ---   noremap GG <Cmd>echom screencol()<CR>
 --- <
 ---
---- @return integer[]
+--- @return integer
 function vim.fn.screencol() end
 
 --- The result is a Dict with the screen position of the text
@@ -7550,7 +7550,7 @@ function vim.fn.screencol() end
 --- @param winid integer
 --- @param lnum integer
 --- @param col integer
---- @return any
+--- @return { col: integer, curscol: integer, endcol: integer, row: integer }
 function vim.fn.screenpos(winid, lnum, col) end
 
 --- The result is a Number, which is the current screen row of the
@@ -7969,7 +7969,7 @@ function vim.fn.searchpairpos(start, middle, end_, flags, skip, stopline, timeou
 --- @param stopline? integer
 --- @param timeout? integer
 --- @param skip? string|function
---- @return any
+--- @return { [1]: integer, [2]: integer, [3]: integer? }
 function vim.fn.searchpos(pattern, flags, stopline, timeout, skip) end
 
 --- Returns a list of server addresses, or empty if all servers

runtime/lua/vim/_meta/vvars_extra.lua

@@ -53,7 +53,7 @@ error('Cannot require a meta file')
 --- `v:event.operator` is "y".
 --- @field operator? string
 --- Text stored in the register as a |readfile()|-style list of lines.
---- @field regcontents? string
+--- @field regcontents? string|string[]
 --- Requested register (e.g "x" for "xyy) or the empty string for an unnamed operation.
 --- @field regname? string
 --- @field regtype? string Type of register as returned by |getregtype()|.

src/nvim/api/vim.c

@@ -1709,15 +1709,15 @@ void nvim_set_client_info(uint64_t channel_id, String name, Dict version, String
 ///         - "stderr"     stderr of this Nvim instance
 ///         - "socket"     TCP/IP socket or named pipe
 ///         - "job"        Job with communication over its stdio.
-///    -  "mode"    How data received on the channel is interpreted.
+///    - "mode"     How data received on the channel is interpreted.
 ///         - "bytes"      Send and receive raw bytes.
 ///         - "terminal"   |terminal| instance interprets ASCII sequences.
 ///         - "rpc"        |RPC| communication on the channel is active.
-///    -  "pty"     (optional) Name of pseudoterminal. On a POSIX system this is a device path like
+///    - "pty"      (optional) Name of pseudoterminal. On a POSIX system this is a device path like
 ///                 "/dev/pts/1". If unknown, the key will still be present if a pty is used (e.g.
 ///                 for conpty on Windows).
-///    -  "buffer"  (optional) Buffer connected to |terminal| instance.
-///    -  "client"  (optional) Info about the peer (client on the other end of the channel), as set
+///    - "buffer"   (optional) Buffer connected to |terminal| instance.
+///    - "client"   (optional) Info about the peer (client on the other end of the channel), as set
 ///                 by |nvim_set_client_info()|.
 ///    - "exitcode" (optional) Exit code of the |terminal| process.
 ///

src/nvim/eval.lua

@@ -8669,7 +8669,7 @@ M.funcs = {
 
     ]=],
     name = 'readdir',
-    params = { { 'directory', 'string' }, { 'expr', 'integer' } },
+    params = { { 'directory', 'string' }, { 'expr', 'integer|string|fun(name: string): integer' } },
     signature = 'readdir({directory} [, {expr}])',
   },
   readfile = {
@@ -9176,7 +9176,7 @@ M.funcs = {
     ]=],
     name = 'screencol',
     params = {},
-    returns = 'integer[]',
+    returns = 'integer',
     signature = 'screencol()',
   },
   screenpos = {
@@ -9209,6 +9209,7 @@ M.funcs = {
     ]=],
     name = 'screenpos',
     params = { { 'winid', 'integer' }, { 'lnum', 'integer' }, { 'col', 'integer' } },
+    returns = '{ col: integer, curscol: integer, endcol: integer, row: integer }',
     signature = 'screenpos({winid}, {lnum}, {col})',
   },
   screenrow = {
@@ -9671,6 +9672,7 @@ M.funcs = {
       { 'timeout', 'integer' },
       { 'skip', 'string|function' },
     },
+    returns = '{ [1]: integer, [2]: integer, [3]: integer? }',
     signature = 'searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])',
   },
   serverlist = {