docs: dev-arch, focusable windows #30510

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

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
---- unwanted behaviour. Some 'shortmess' flags and similar
---- mechanism might fail to take effect, causing unwanted hit-enter
---- prompts.  Some informative messages, both from Nvim itself and
---- plugins, will not be displayed.
+--- WARNING: `cmdheight=0` is EXPERIMENTAL. Expect some unwanted behaviour.
+--- Some 'shortmess' flags and similar mechanism might fail to take effect,
+--- causing unwanted hit-enter prompts.  Some informative messages, both
+--- from Nvim itself and 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"
---- and case-sensitive by default, regardless of 'magic' and 'ignorecase'.
---- They can be controlled with flags, see |/magic| and |/ignorecase|.
+--- 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|.
 --- @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
---- precisely, surround the regex with `^` and `$`. If there was a match, the
---- byte indices for the beginning and end of the match are returned. When
---- there is no match, `nil` is returned. Because any integer is "truthy",
---- `regex:match_str()` can be directly used as a condition in an if-statement.
+--- Matches string `str` against this regex. To match the string precisely, surround the regex with
+--- "^" and "$". Returns the byte indices for the start and end of the match, or `nil` if there is
+--- no match. Because any integer is "truthy", `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}
---- are supplied, match only this byte index range. Otherwise see
---- |regex:match_str()|. If {start} is used, then the returned byte indices
---- will be relative {start}.
+--- Matches line at `line_idx` (zero-based) in buffer `bufnr`. Match is restricted to byte index
+--- range `start` and `end_` if given, otherwise see |regex:match_str()|. Returned byte indices are
+--- relative to `start` if given.
 --- @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 expr1 any
+--- @param expr number
+--- @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