docs: dev-arch, focusable windows #30510

- 'statuscolumn' is no longer experimental
- add tags for popular searches on neovim.io

contrib/minimal.lua

@@ -2,7 +2,8 @@
 
 for name, url in pairs {
   -- ADD PLUGINS _NECESSARY_ TO REPRODUCE THE ISSUE, e.g:
-  -- some_plugin = 'https://github.com/author/plugin.nvim'
+  -- 'https://github.com/author1/plugin1',
+  -- 'https://github.com/author2/plugin2',
 } do
   local install_path = vim.fn.fnamemodify('nvim_issue/' .. name, ':p')
   if vim.fn.isdirectory(install_path) == 0 then

runtime/doc/builtin.txt

@@ -26,7 +26,7 @@ abs({expr})                                                              *abs()*
 <			4
 
                 Parameters: ~
-                  • {expr} (`any`)
+                  • {expr} (`number`)
 
                 Return: ~
                   (`number`)
@@ -45,7 +45,7 @@ acos({expr})                                                            *acos()*
 <			2.094395
 
                 Parameters: ~
-                  • {expr} (`any`)
+                  • {expr} (`number`)
 
                 Return: ~
                   (`number`)
@@ -78,8 +78,8 @@ and({expr}, {expr})                                                      *and()*
 <
 
                 Parameters: ~
-                  • {expr} (`any`)
+                  • {expr} (`number`)
-                  • {expr1} (`any`)
+                  • {expr1} (`number`)
 
                 Return: ~
                   (`integer`)
@@ -111,7 +111,7 @@ append({lnum}, {text})                                                *append()*
 
                 Parameters: ~
                   • {lnum} (`integer`)
-                  • {text} (`any`)
+                  • {text} (`string|string[]`)
 
                 Return: ~
                   (`0|1`)

runtime/doc/dev_arch.txt

@@ -0,0 +1,59 @@
+*dev_arch.txt*          Nvim
+
+
+                            NVIM REFERENCE MANUAL
+
+
+How to develop Nvim, explanation of modules and subsystems    *dev-arch*
+
+The top of each major module has (or should have) an overview in a comment at
+the top of its file. The purpose of this document is to give:
+
+1. an overview of how it all fits together
+2. how-to guides for common tasks such as:
+    - deprecating public functions
+    - adding a new public (API) function
+    - adding a new public (UI) event
+3. TODO: move src/nvim/README.md into this doc.
+
+                                  Type |gO| to see the table of contents.
+
+==============================================================================
+Data structures
+
+Use `kvec.h` for most lists. When you absolutely need a linked list, use
+`lib/queue_defs.h` which defines an "intrusive" linked list.
+
+==============================================================================
+UI events
+
+The source files most directly involved with UI events are:
+1. `src/nvim/ui.*`: calls handler functions of registered UI structs (independent from msgpack-rpc)
+2. `src/nvim/api/ui.*`: forwards messages over msgpack-rpc to remote UIs.
+
+UI events are defined in `src/nvim/api/ui_events.in.h` , this file is not
+compiled directly, rather it parsed by
+`src/nvim/generators/gen_api_ui_events.lua` which autogenerates wrapper
+functions used by the source files above. It also generates metadata
+accessible as `api_info().ui_events`.
+
+See commit d3a8e9217f39c59dd7762bd22a76b8bd03ca85ff for an example of adding
+a new UI event.
+
+UI events are deferred to UIs, which implies a deepcopy of the UI event data.
+
+Remember to bump NVIM_API_LEVEL if it wasn't already during this development
+cycle.
+
+Other references:
+* |msgpack-rpc|
+* |ui|
+* https://github.com/neovim/neovim/pull/3246
+* https://github.com/neovim/neovim/pull/18375
+* https://github.com/neovim/neovim/pull/21605
+
+
+
+==============================================================================
+
+vim:tw=78:ts=8:sw=4:et:ft=help:norl:

runtime/doc/dev_tools.txt

@@ -7,7 +7,9 @@
 Tools and techniques for developing Nvim                        *dev-tools*
 
 The following advice is helpful when working on or debugging issues with Nvim
-itself. See also |debug.txt| for advice that applies to Vim.
+itself.
+
+TODO: merge |debug.txt| into here.
 
                                   Type |gO| to see the table of contents.
 

runtime/doc/develop.txt

@@ -7,8 +7,8 @@
 Development of Nvim                                     *development* *dev*
 
 This reference describes design constraints and guidelines, for developing
-Nvim applications or Nvim itself.
+Nvim applications or Nvim itself. See |dev-arch| for discussion of Nvim's
-Architecture and internal concepts are covered in src/nvim/README.md
+architecture and internal concepts.
 
 Nvim is free and open source.  Everybody is encouraged to contribute.
     https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md

runtime/doc/gui.txt

@@ -639,9 +639,6 @@ a menu item - you don't need to do a :tunmenu as well.
 You can cause a menu to popup at the cursor.  This behaves similarly to the
 PopUp menus except that any menu tree can be popped up.
 
-This command is for backwards compatibility, using it is discouraged, because
-it behaves in a strange way.
-
 							*:popup* *:popu*
 :popu[p] {name}			Popup the menu {name}.  The menu named must
 				have at least one subentry, but need not

runtime/doc/help.txt

@@ -169,6 +169,7 @@ VERSIONS
 DEVELOPING NVIM
 
 |dev|			Development of Nvim
+|dev-arch|		Internal architecture, modules, data structures
 |dev-style|		Development style guidelines
 |dev-theme|		Design guidelines (colorschemes etc.)
 |dev-tools|		Tools and techniques for developing Nvim

runtime/doc/lsp.txt

@@ -321,7 +321,7 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
     }
 <
   Some handlers do not have an explicitly named handler function (such as
-  ||vim.lsp.diagnostic.on_publish_diagnostics()|). To override these, first
+  |vim.lsp.diagnostic.on_publish_diagnostics()|). To override these, first
   create a reference to the existing handler: >lua
 
     local on_references = vim.lsp.handlers["textDocument/references"]

runtime/doc/lua.txt

@@ -3652,10 +3652,10 @@ within a single line.
 
                                                           *regex:match_line()*
 regex:match_line({bufnr}, {line_idx}, {start}, {end_})
-    Match line {line_idx} (zero-based) in buffer {bufnr}. If {start} and {end}
+    Matches line at `line_idx` (zero-based) in buffer `bufnr`. Match is
-    are supplied, match only this byte index range. Otherwise see
+    restricted to byte index range `start` and `end_` if given, otherwise see
-    |regex:match_str()|. If {start} is used, then the returned byte indices
+    |regex:match_str()|. Returned byte indices are relative to `start` if
-    will be relative {start}.
+    given.
 
     Parameters: ~
       • {bufnr}     (`integer`)
@@ -3663,19 +3663,28 @@ regex:match_line({bufnr}, {line_idx}, {start}, {end_})
       • {start}     (`integer?`)
       • {end_}      (`integer?`)
 
+    Return (multiple): ~
+        (`integer?`) match start (byte index) relative to `start`, or `nil` if
+        no match
+        (`integer?`) match end (byte index) relative to `start`, or `nil` if
+        no match
+
 regex:match_str({str})                                     *regex:match_str()*
-    Match the string against the regex. If the string should match the regex
+    Matches string `str` against this regex. To match the string precisely,
-    precisely, surround the regex with `^` and `$`. If there was a match, the
+    surround the regex with "^" and "$". Returns the byte indices for the
-    byte indices for the beginning and end of the match are returned. When
+    start and end of the match, or `nil` if there is no match. Because any
-    there is no match, `nil` is returned. Because any integer is "truthy",
+    integer is "truthy", `regex:match_str()` can be directly used as a
-    `regex:match_str()` can be directly used as a condition in an
+    condition in an if-statement.
-    if-statement.
 
     Parameters: ~
       • {str}  (`string`)
 
+    Return (multiple): ~
+        (`integer?`) match start (byte index), or `nil` if no match
+        (`integer?`) match end (byte index), or `nil` if no match
+
 vim.regex({re})                                                  *vim.regex()*
-    Parse the Vim regex {re} and return a regex object. Regexes are "magic"
+    Parses the Vim regex `re` and returns a regex object. Regexes are "magic"
     and case-sensitive by default, regardless of 'magic' and 'ignorecase'.
     They can be controlled with flags, see |/magic| and |/ignorecase|.
 

runtime/doc/news.txt

@@ -29,6 +29,7 @@ These changes may require adaptations in your config or plugins.
 
 API
 
+• Improved API "meta" docstrings and :help documentation.
 • `vim.rpcnotify(0)` and `rpcnotify(0)` broadcast to ALL channels. Previously
   they would "multicast" only to subscribed channels (controlled by
   `nvim_subscribe()`). Plugins and clients that want "multicast" behavior must
@@ -69,6 +70,7 @@ EVENTS
 
 LSP
 
+• Improved rendering of LSP hover docs. |K-lsp-default|
 • |vim.lsp.completion.enable()| gained the `convert` callback which enables
   customizing the transformation of an LSP CompletionItem to |complete-items|.
 • |vim.lsp.diagnostic.from()| can be used to convert a list of

runtime/doc/nvim.txt

@@ -4,7 +4,7 @@
                             NVIM REFERENCE MANUAL
 
 
-Nvim                                                       *nvim* *nvim-intro*
+Nvim                                              *neovim* *nvim* *nvim-intro*
 
 Nvim is based on Vim by Bram Moolenaar.
 

runtime/doc/options.txt

@@ -1424,11 +1424,10 @@ A jump table for the options with a short description can be found at |Q_op|.
 	used.  The command-line will cover the last line of the screen when
 	shown.
 
-	WARNING: `cmdheight=0` is considered experimental. Expect some
+	WARNING: `cmdheight=0` is EXPERIMENTAL. Expect some unwanted behaviour.
-	unwanted behaviour. Some 'shortmess' flags and similar
+	Some 'shortmess' flags and similar mechanism might fail to take effect,
-	mechanism might fail to take effect, causing unwanted hit-enter
+	causing unwanted hit-enter prompts.  Some informative messages, both
-	prompts.  Some informative messages, both from Nvim itself and
+	from Nvim itself and plugins, will not be displayed.
-	plugins, will not be displayed.
 
 						*'cmdwinheight'* *'cwh'*
 'cmdwinheight' 'cwh'	number	(default 7)
@@ -6027,7 +6026,6 @@ A jump table for the options with a short description can be found at |Q_op|.
 						*'statuscolumn'* *'stc'*
 'statuscolumn' 'stc'	string	(default "")
 			local to window
-	EXPERIMENTAL
 	When non-empty, this option determines the content of the area to the
 	side of a window, normally containing the fold, sign and number columns.
 	The format of this option is like that of 'statusline'.

runtime/doc/syntax.txt

@@ -5092,11 +5092,13 @@ guisp={color-name}					*guisp*
 	All values are hexadecimal, range from "00" to "ff".  Examples: >
 	    :highlight Comment guifg=#11f0c3 guibg=#ff00ff
 <
-blend={integer}					*highlight-blend*
+blend={integer}					*highlight-blend* *opacity*
 	Override the blend level for a highlight group within the popupmenu
 	or floating windows. Only takes effect if 'pumblend' or 'winblend'
 	is set for the menu or window. See the help at the respective option.
 
+	See also the "blend" flag of |nvim_buf_set_extmark()|.
+
 					*highlight-groups* *highlight-default*
 These are the builtin highlighting groups.  Note that the highlighting depends
 on the value of 'background'.  You can see the current settings with the

runtime/doc/terminal.txt

@@ -201,7 +201,7 @@ Example: >vim
 
 Use |jobwait()| to check if the terminal job has finished: >vim
     let running = jobwait([&channel], 0)[0] == -1
-
+<
 ==============================================================================
 :Termdebug plugin				*terminal-debug*
 

runtime/doc/windows.txt

@@ -64,6 +64,16 @@ will not change.
 The main Vim window can hold several split windows.  There are also tab pages
 |tab-page|, each of which can hold multiple windows.
 
+							*focusable*
+If a window is focusable, it is part of the "navigation stack", that is,
+editor commands such as :windo, |CTRL-W|, etc., will consider the window as
+one that can be made the "current window". A non-focusable window will be
+skipped by such commands (though it can be explicitly focused by
+|nvim_set_current_win()|).
+
+Windows (especially floating windows) can have many other |api-win_config|
+properties such as "hide" and "fixed" which also affect behavior.
+
 					*window-ID* *winid* *windowid*
 Each window has a unique identifier called the window ID.  This identifier
 will not change within a Vim session. The |win_getid()| and |win_id2tabwin()|
@@ -426,18 +436,19 @@ CTRL-W l	Move cursor to Nth window right of current one.  Uses the
 		cursor position to select between alternatives.
 
 CTRL-W w					*CTRL-W_w* *CTRL-W_CTRL-W*
-CTRL-W CTRL-W	Without count: move cursor to window below/right of the
+CTRL-W CTRL-W	Without count: move cursor to the |focusable| window
-		current one.  If there is no window below or right, go to
+		below/right of the current one.  If there is no (focusable)
-		top-left window.
+		window below or right, go to top-left window. With count: go
-		With count: go to Nth window (windows are numbered from
+		to Nth window (windows are numbered from top-left to
-		top-left to bottom-right).  To obtain the window number see
+		bottom-right).  To obtain the window number see |bufwinnr()|
-		|bufwinnr()| and |winnr()|.  When N is larger than the number
+		and |winnr()|.  When N is larger than the number of windows go
-		of windows go to the last window.
+		to the last window.
 
 						*CTRL-W_W*
-CTRL-W W	Without count: move cursor to window above/left of current
+CTRL-W W	Without count: move cursor to the |focusable| window
-		one.  If there is no window above or left, go to bottom-right
+		above/left of current one.  If there is no window above or
-		window.  With count: go to Nth window, like with CTRL-W w.
+		left, go to bottom-right window.  With count: go to Nth
+		window, like with CTRL-W w.
 
 CTRL-W t					*CTRL-W_t* *CTRL-W_CTRL-T*
 CTRL-W CTRL-T	Move cursor to top-left window.
@@ -794,9 +805,9 @@ can also get to them with the buffer list commands, like ":bnext".
 8. Do a command in all buffers or windows			*list-repeat*
 
 							*:windo*
-:[range]windo {cmd}	Execute {cmd} in each window or if [range] is given
+:[range]windo {cmd}	Execute {cmd} in each |focusable| window, or only for
-			only in windows for which the window number lies in
+			windows in a given [range] of window numbers. It works
-			the [range]. It works like doing this: >
+			like doing this: >
 				CTRL-W t
 				:{cmd}
 				CTRL-W w

runtime/lua/vim/_meta/options.lua

@@ -914,11 +914,10 @@ vim.go.cb = vim.go.clipboard
 --- used.  The command-line will cover the last line of the screen when
 --- shown.
 ---
---- WARNING: `cmdheight=0` is considered experimental. Expect some
+--- WARNING: `cmdheight=0` is EXPERIMENTAL. Expect some unwanted behaviour.
---- unwanted behaviour. Some 'shortmess' flags and similar
+--- Some 'shortmess' flags and similar mechanism might fail to take effect,
---- mechanism might fail to take effect, causing unwanted hit-enter
+--- causing unwanted hit-enter prompts.  Some informative messages, both
---- prompts.  Some informative messages, both from Nvim itself and
+--- from Nvim itself and plugins, will not be displayed.
---- plugins, will not be displayed.
 ---
 --- @type integer
 vim.o.cmdheight = 1
@@ -6431,7 +6430,6 @@ vim.o.sol = vim.o.startofline
 vim.go.startofline = vim.o.startofline
 vim.go.sol = vim.go.startofline
 
---- EXPERIMENTAL
 --- When non-empty, this option determines the content of the area to the
 --- side of a window, normally containing the fold, sign and number columns.
 --- The format of this option is like that of 'statusline'.

runtime/lua/vim/_meta/regex.lua

@@ -5,9 +5,9 @@
 --- @brief Vim regexes can be used directly from Lua. Currently they only allow
 --- matching within a single line.
 
---- Parse the Vim regex {re} and return a regex object. Regexes are "magic"
+--- Parses the Vim regex `re` and returns a regex object. Regexes are "magic" and case-sensitive by
---- and case-sensitive by default, regardless of 'magic' and 'ignorecase'.
+--- default, regardless of 'magic' and 'ignorecase'. They can be controlled with flags, see |/magic|
---- They can be controlled with flags, see |/magic| and |/ignorecase|.
+--- and |/ignorecase|.
 --- @param re string
 --- @return vim.regex
 function vim.regex(re) end
@@ -16,20 +16,22 @@ function vim.regex(re) end
 --- @class vim.regex
 local regex = {} -- luacheck: no unused
 
---- Match the string against the regex. If the string should match the regex
+--- Matches string `str` against this regex. To match the string precisely, surround the regex with
---- precisely, surround the regex with `^` and `$`. If there was a match, the
+--- "^" and "$". Returns the byte indices for the start and end of the match, or `nil` if there is
---- byte indices for the beginning and end of the match are returned. When
+--- no match. Because any integer is "truthy", `regex:match_str()` can be directly used as
---- there is no match, `nil` is returned. Because any integer is "truthy",
+--- a condition in an if-statement.
---- `regex:match_str()` can be directly used as a condition in an if-statement.
 --- @param str string
+--- @return integer? # match start (byte index), or `nil` if no match
+--- @return integer? # match end (byte index), or `nil` if no match
 function regex:match_str(str) end
 
---- Match line {line_idx} (zero-based) in buffer {bufnr}. If {start} and {end}
+--- Matches line at `line_idx` (zero-based) in buffer `bufnr`. Match is restricted to byte index
---- are supplied, match only this byte index range. Otherwise see
+--- range `start` and `end_` if given, otherwise see |regex:match_str()|. Returned byte indices are
---- |regex:match_str()|. If {start} is used, then the returned byte indices
+--- relative to `start` if given.
---- will be relative {start}.
 --- @param bufnr integer
 --- @param line_idx integer
 --- @param start? integer
 --- @param end_? integer
+--- @return integer? # match start (byte index) relative to `start`, or `nil` if no match
+--- @return integer? # match end (byte index) relative to `start`, or `nil` if no match
 function regex:match_line(bufnr, line_idx, start, end_) end

runtime/lua/vim/_meta/vimfn.lua

@@ -15,7 +15,7 @@ error('Cannot require a meta file')
 ---   echo abs(-4)
 --- <  4
 ---
---- @param expr any
+--- @param expr number
 --- @return number
 function vim.fn.abs(expr) end
 
@@ -31,7 +31,7 @@ function vim.fn.abs(expr) end
 ---   echo acos(-0.5)
 --- <  2.094395
 ---
---- @param expr any
+--- @param expr number
 --- @return number
 function vim.fn.acos(expr) end
 
@@ -57,8 +57,8 @@ function vim.fn.add(object, expr) end
 ---   let flag = and(bits, 0x80)
 --- <
 ---
---- @param expr any
+--- @param expr number
---- @param expr1 any
+--- @param expr1 number
 --- @return integer
 vim.fn['and'] = function(expr, expr1) end
 
@@ -86,7 +86,7 @@ function vim.fn.api_info() end
 --- <
 ---
 --- @param lnum integer
---- @param text any
+--- @param text string|string[]
 --- @return 0|1
 function vim.fn.append(lnum, text) end
 

src/nvim/eval.lua

@@ -54,7 +54,7 @@ M.funcs = {
 
     ]=],
     name = 'abs',
-    params = { { 'expr', 'any' } },
+    params = { { 'expr', 'number' } },
     signature = 'abs({expr})',
     returns = 'number',
   },
@@ -77,7 +77,7 @@ M.funcs = {
     ]=],
     float_func = 'acos',
     name = 'acos',
-    params = { { 'expr', 'any' } },
+    params = { { 'expr', 'number' } },
     returns = 'number',
     signature = 'acos({expr})',
   },
@@ -114,7 +114,7 @@ M.funcs = {
       <
     ]=],
     name = 'and',
-    params = { { 'expr', 'any' }, { 'expr', 'any' } },
+    params = { { 'expr', 'number' }, { 'expr', 'number' } },
     returns = 'integer',
     signature = 'and({expr}, {expr})',
   },
@@ -152,7 +152,7 @@ M.funcs = {
 
     ]=],
     name = 'append',
-    params = { { 'lnum', 'integer' }, { 'text', 'any' } },
+    params = { { 'lnum', 'integer' }, { 'text', 'string|string[]' } },
     returns = '0|1',
     signature = 'append({lnum}, {text})',
   },

src/nvim/log.c

@@ -258,6 +258,7 @@ void log_callstack_to_file(FILE *log_file, const char *const func_name, const in
 
   do_log_to_file(log_file, LOGLVL_DBG, NULL, func_name, line_num, true, "trace:");
   FILE *fp = popen(cmdbuf, "r");
+  assert(fp);
   char linebuf[IOSIZE];
   while (fgets(linebuf, sizeof(linebuf) - 1, fp) != NULL) {
     fprintf(log_file, "  %s", linebuf);

src/nvim/options.lua

@@ -1,3 +1,5 @@
+-- vim: tw=80
+
 --- @class vim.option_meta
 --- @field full_name string
 --- @field desc? string
@@ -1229,11 +1231,10 @@ return {
         used.  The command-line will cover the last line of the screen when
         shown.
 
-        WARNING: `cmdheight=0` is considered experimental. Expect some
+        WARNING: `cmdheight=0` is EXPERIMENTAL. Expect some unwanted behaviour.
-        unwanted behaviour. Some 'shortmess' flags and similar
+        Some 'shortmess' flags and similar mechanism might fail to take effect,
-        mechanism might fail to take effect, causing unwanted hit-enter
+        causing unwanted hit-enter prompts.  Some informative messages, both
-        prompts.  Some informative messages, both from Nvim itself and
+        from Nvim itself and plugins, will not be displayed.
-        plugins, will not be displayed.
       ]=],
       full_name = 'cmdheight',
       redraw = { 'all_windows' },
@@ -8096,7 +8097,6 @@ return {
       cb = 'did_set_statuscolumn',
       defaults = { if_true = '' },
       desc = [=[
-        EXPERIMENTAL
         When non-empty, this option determines the content of the area to the
         side of a window, normally containing the fold, sign and number columns.
         The format of this option is like that of 'statusline'.