From a3b48b1054d01084face54d830f35c7a5a4e35a4 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Fri, 20 Mar 2026 23:52:42 +0100 Subject: [PATCH] docs: api, plugins, ui2 --- runtime/doc/api.txt | 54 +++++++++++++------ runtime/doc/dev_arch.txt | 3 +- runtime/doc/lsp.txt | 39 +++++++++++--- runtime/doc/lua.txt | 15 +++--- runtime/doc/news.txt | 2 +- runtime/doc/nvim.txt | 3 +- runtime/doc/options.txt | 8 +-- runtime/doc/plugins.txt | 12 ++--- runtime/doc/spell.txt | 2 +- runtime/doc/undo.txt | 2 +- runtime/doc/various.txt | 3 ++ runtime/doc/vim_diff.txt | 6 +-- runtime/doc/vimfn.txt | 2 +- runtime/example_init.lua | 2 +- runtime/lua/vim/_core/editor.lua | 5 +- runtime/lua/vim/_core/ui2.lua | 2 +- runtime/lua/vim/_meta/api.lua | 36 +++++++++++-- runtime/lua/vim/_meta/options.lua | 8 +-- runtime/lua/vim/_meta/vimfn.lua | 2 +- runtime/lua/vim/lsp.lua | 2 +- runtime/lua/vim/net.lua | 7 +-- src/gen/gen_eval_files.lua | 6 +++ src/gen/gen_vimdoc.lua | 15 +++--- src/nvim/api/extmark.c | 4 -- src/nvim/api/vim.c | 6 --- src/nvim/eval.lua | 2 +- src/nvim/options.lua | 8 +-- test/functional/treesitter/highlight_spec.lua | 3 +- 28 files changed, 157 insertions(+), 102 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 0423eafa40..c878251a88 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -154,13 +154,18 @@ indices, end-inclusive): - |nvim_buf_get_extmarks()| - |nvim_buf_set_extmark()| - *api-fast* -Most API functions are "deferred": they are queued on the main loop and -processed sequentially with normal input. So if the editor is waiting for -user input in a "modal" fashion (e.g. an |input()| prompt), the request -will block. Non-deferred (fast) functions such as |nvim_get_mode()| and -|nvim_input()| are served immediately (i.e. without waiting in the input -queue). Lua code can use |vim.in_fast_event()| to detect a fast context. + *api-fast* *schedule* +Most API functions are deferred: they are queued ("scheduled") on the main +loop and processed sequentially with normal input. If the editor is waiting +for user input in a "modal" fashion (e.g. an |input()| prompt), a deferred +request will block. +- Non-deferred (fast) functions such |nvim_get_mode()|, |nvim_input()|, or any + Lua callback, are executed immediately (not sequenced in the input queue). +- Lua code can use |vim.in_fast_event()| to detect a fast context, where it + may interact with Lua state but not "editor" state (|textlock|, options, + window layout, …). +- To perform editor operations, Lua code must schedule via |vim.defer_fn()| or + |vim.schedule()|, or wait until `vim.in_fast_event()` returns `false`. ============================================================================== API metadata *api-metadata* @@ -345,11 +350,10 @@ User reloads the buffer with ":edit", emits: > LUA ~ *api-buffer-updates-lua* -In-process Lua plugins can receive buffer updates in the form of Lua -callbacks. These callbacks are called frequently in various contexts; -|textlock| prevents changing buffer contents and window layout (use -|vim.schedule()| to defer such operations to the main loop instead). -Moving the cursor is allowed, but it is restored afterwards. +In-process plugins can receive buffer updates via Lua callbacks. These +callbacks are called frequently in various contexts; |textlock| prevents +changing buffer contents and window layout (such operations must be +|schedule|d). Moving the cursor is allowed, but it is restored afterwards. |nvim_buf_attach()| will take keyword args for the callbacks. "on_lines" will receive parameters ("lines", {buf}, {changedtick}, {firstline}, {lastline}, @@ -1682,7 +1686,7 @@ nvim_strwidth({text}) *nvim_strwidth()* (`integer`) Number of cells nvim__complete_set({index}, {opts}) *nvim__complete_set()* - EXPERIMENTAL: this API may change in the future. + WARNING: This feature is experimental/unstable. Sets info for the completion item at the given index. If the info text was shown in a window, returns the window and buffer ids, or empty dict if not @@ -1699,7 +1703,7 @@ nvim__complete_set({index}, {opts}) *nvim__complete_set()* • bufnr: (number) buffer id in floating window nvim__exec_lua_fast({code}, {args}) *nvim__exec_lua_fast()* - EXPERIMENTAL: this API may change or be removed in the future. + WARNING: This feature is experimental/unstable. Like |nvim_exec_lua()|, but can be called during |api-fast| contexts. @@ -1722,6 +1726,8 @@ nvim__exec_lua_fast({code}, {args}) *nvim__exec_lua_fast()* (`any`) Return value of Lua code if present or NIL. nvim__get_runtime({pat}, {all}, {opts}) *nvim__get_runtime()* + WARNING: This feature is experimental/unstable. + Find files in runtime directories Attributes: ~ @@ -1737,6 +1743,8 @@ nvim__get_runtime({pat}, {all}, {opts}) *nvim__get_runtime()* (`string[]`) list of absolute paths to the found files nvim__id({obj}) *nvim__id()* + WARNING: This feature is experimental/unstable. + Returns object given as argument. This API function is used for testing. One should not rely on its presence @@ -1749,6 +1757,8 @@ nvim__id({obj}) *nvim__id()* (`any`) its argument. nvim__id_array({arr}) *nvim__id_array()* + WARNING: This feature is experimental/unstable. + Returns array given as argument. This API function is used for testing. One should not rely on its presence @@ -1761,6 +1771,8 @@ nvim__id_array({arr}) *nvim__id_array()* (`any[]`) its argument. nvim__id_dict({dct}) *nvim__id_dict()* + WARNING: This feature is experimental/unstable. + Returns dict given as argument. This API function is used for testing. One should not rely on its presence @@ -1773,6 +1785,8 @@ nvim__id_dict({dct}) *nvim__id_dict()* (`table`) its argument. nvim__id_float({flt}) *nvim__id_float()* + WARNING: This feature is experimental/unstable. + Returns floating-point value given as argument. This API function is used for testing. One should not rely on its presence @@ -1785,6 +1799,8 @@ nvim__id_float({flt}) *nvim__id_float()* (`number`) its argument. nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* + WARNING: This feature is experimental/unstable. + NB: if your UI doesn't use hlstate, this will not return hlstate first time. @@ -1797,11 +1813,13 @@ nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* (`any[]`) nvim__invalidate_glyph_cache() *nvim__invalidate_glyph_cache()* + WARNING: This feature is experimental/unstable. + For testing. The condition in schar_cache_clear_if_full is hard to reach, so this function can be used to force a cache clear in a test. nvim__redraw({opts}) *nvim__redraw()* - EXPERIMENTAL: this API may change in the future. + WARNING: This feature is experimental/unstable. Instruct Nvim to redraw various components. @@ -1833,6 +1851,8 @@ nvim__redraw({opts}) *nvim__redraw()* • |:redraw| nvim__stats() *nvim__stats()* + WARNING: This feature is experimental/unstable. + Gets internal stats. Return: ~ @@ -3414,7 +3434,7 @@ nvim_set_decoration_provider({ns_id}, {opts}) < nvim__ns_get({ns_id}) *nvim__ns_get()* - EXPERIMENTAL: this API will change in the future. + WARNING: This feature is experimental/unstable. Get the properties for namespace @@ -3426,7 +3446,7 @@ nvim__ns_get({ns_id}) *nvim__ns_get()* |nvim__ns_set()| nvim__ns_set({ns_id}, {opts}) *nvim__ns_set()* - EXPERIMENTAL: this API will change in the future. + WARNING: This feature is experimental/unstable. Set some properties for namespace diff --git a/runtime/doc/dev_arch.txt b/runtime/doc/dev_arch.txt index ee6939ed44..b105d1e8d4 100644 --- a/runtime/doc/dev_arch.txt +++ b/runtime/doc/dev_arch.txt @@ -56,7 +56,8 @@ Lua code lives in one of four places: primarily user-facing, not an API. - "Opt-out" plugins (activated on startup): `runtime/plugin/` - "Opt-in" plugins (activated via `:packadd`): `runtime/pack/dist/opt/` - - NOTE: New plugins should place Lua modules in the shared "nvim" + - Note: Update |standard-plugin-list|. + - Note: New plugins should place Lua modules in the shared "nvim" namespace: `require('nvim.foo')`, not `require('foo')`. - Examples: - ✅ spellfile `runtime/lua/nvim/spellfile.lua` diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 39be03c5e4..7361514628 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -370,6 +370,17 @@ LSP handlers are functions that handle |lsp-response|s to requests made by Nvim to the server. (Notifications, as opposed to requests, are fire-and-forget: there is no response, so they can't be handled. |lsp-notification|) +Each handler has the following signature: > + + vim.lsp.ResponseHandler: + fun(err, result, ctx) + + vim.lsp.NotificationHandler: + fun(err, params, ctx) + + vim.lsp.RequestHandler: + fun(err, params, ctx): Result?, lsp.ResponseError? + Each response handler has this signature: > function(err, result, ctx) @@ -390,10 +401,15 @@ Each response handler has this signature: > current document version to check if the response is "stale". See also |b:changedtick|. - Returns: ~ - Two values `result, err` where `err` is shaped like an RPC error: > + Return (multiple): ~ + • (`Result?`) `result` on success, or `nil` on error. + • (`lsp.ResponseError?`) `error` on failure, or `nil` on success. + RPC error shape: > { code, message, data? } -< You can use |vim.lsp.rpc.rpc_response_error()| to create this object. +< You can use |vim.lsp.rpc.rpc_response_error()| to create this object. + + |lsp-response| and |lsp-notification| handlers do not have return + values. *lsp-handler-resolution* Handlers can be set by (in increasing priority): @@ -450,12 +466,23 @@ name: >lua vim.lsp.protocol.TextDocumentSyncKind[1] == "Full" < + *lsp-request* +LSP request shape: > + { id: integer|string, method: string, params?: Params } +< +https://microsoft.github.io/language-server-protocol/specifications/specification-current/#requestMessage + *lsp-response* -LSP response shape: +LSP response shape: > + { id: integer|string|nil, result: Result, error: nil } (on success) + { id: integer|string|nil, result: nil, error: ResponseError } (on error) +< https://microsoft.github.io/language-server-protocol/specifications/specification-current/#responseMessage *lsp-notification* -LSP notification shape: +LSP notification shape: > + { method: string, params?: Params } +< https://microsoft.github.io/language-server-protocol/specifications/specification-current/#notificationMessage ================================================================================ @@ -1136,7 +1163,7 @@ get_client_by_id({client_id}) *vim.lsp.get_client_by_id()* (`vim.lsp.Client?`) client rpc object. See |vim.lsp.Client|. get_clients({filter}) *vim.lsp.get_clients()* - Get active clients. + Gets active clients. Attributes: ~ Since: 0.10.0 diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index b676f3203d..4aa57dda05 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -483,7 +483,7 @@ It is an error to directly invoke `vim.api` functions (except |api-fast|) in vim.api.nvim_command('echomsg "test"') end) < -To avoid the error use |vim.schedule_wrap()| to defer the callback: >lua +To avoid the error, |schedule| the callback: >lua local timer = vim.uv.new_timer() timer:start(1000, 0, vim.schedule_wrap(function() @@ -1279,8 +1279,8 @@ vim.cmd({command}) *vim.cmd()* vim.defer_fn({fn}, {timeout}) *vim.defer_fn()* Defers calling {fn} until {timeout} ms passes. - Use to do a one-shot timer that calls {fn} Note: The {fn} is - |vim.schedule()|d automatically, so API functions are safe to call. + Use to do a one-shot timer that calls {fn}. Note: The {fn} is |schedule|d + automatically, so API functions are safe to call. Parameters: ~ • {fn} (`function`) Callback to call once `timeout` expires @@ -4156,11 +4156,8 @@ Lua module: vim.net *vim.net* vim.net.request({url}, {opts}, {on_response}) *vim.net.request()* - Makes an HTTP GET request to the given URL (asynchronous). - - This function is asynchronous (non-blocking), returning immediately and - passing the response object to the optional `on_response` handler on - completion. + Makes an HTTP GET request to the given URL, asynchronously passing the + result to the specified `on_response`, `outpath` or `outbuf`. Examples: >lua -- Write response body to file @@ -5452,7 +5449,7 @@ To enable this feature (default opts shown): >lua There are four special windows/buffers for presenting messages and cmdline: • "cmd": Cmdline. Also used for 'showcmd', 'showmode', 'ruler', and messages by default. -• "msg": Message window, shows fleeting messages useful for 'cmdheight' == 0. +• "msg": Message window, shows ephemeral messages useful for 'cmdheight' == 0. • "pager": Pager window, shows |:messages| and certain messages that are never "collapsed". • "dialog": Dialog window, shows modal prompts that expect user input. diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 8535fbb7fa..2c5e9a6d7d 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -129,7 +129,7 @@ OPTIONS PLUGINS • Removed "shellmenu" plugin, an old menu-based quasi-snippet plugin for shell scripts. -• |tohtml| is now an "opt-in" plugin. Use |:packadd| to activate it: > +• |package-tohtml| is now an "opt-in" plugin. Use |:packadd| to activate it: > :packadd nvim.tohtml TREESITTER diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt index e83ca8c1d5..032176e56b 100644 --- a/runtime/doc/nvim.txt +++ b/runtime/doc/nvim.txt @@ -25,6 +25,7 @@ To learn how to use Vim in 30 minutes, try the tutorial: >vim < Or watch this 10-minute video: https://youtu.be/TQn2hJeHQbM . + *config-example* *example-init* To customize Nvim, you will need a config file. Create your |init.lua| by copying the "example_init.lua" file: >vim @@ -43,7 +44,7 @@ not support them): - *lazyvim* https://www.lazyvim.org/ - *nvchad* https://nvchad.com/ - *kickstart* https://github.com/nvim-lua/kickstart.nvim - - Not recommended; use `$VIMRUNTIME/example_init.lua` instead. + - Not recommended; use |example-init| instead. However, we recommend (eventually) taking time to learn Nvim from its stock configuration, and incrementally setting options and adding plugins to your diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 0bca1c43bd..f0d9033855 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -1481,10 +1481,7 @@ 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 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. Works better with |ui2| enabled. *'cmdwinheight'* *'cwh'* 'cmdwinheight' 'cwh' number (default 7) @@ -3908,7 +3905,6 @@ A jump table for the options with a short description can be found at |Q_op|. the action occurred. clean Remove unloaded buffers from the jumplist. - EXPERIMENTAL: this flag may change in the future. *'keymap'* *'kmp'* 'keymap' 'kmp' string (default "") @@ -6136,7 +6132,7 @@ A jump table for the options with a short description can be found at |Q_op|. encoding is used, Vim doesn't check it. How the related spell files are found is explained here: |spell-load|. - If the |spellfile.lua| plugin is active and you use a language name + If the |package-spellfile| plugin is active and you use a language name for which Vim cannot find the .spl file in 'runtimepath' the plugin will ask you if you want to download the file. diff --git a/runtime/doc/plugins.txt b/runtime/doc/plugins.txt index e36fd7f8ec..bc49e25880 100644 --- a/runtime/doc/plugins.txt +++ b/runtime/doc/plugins.txt @@ -28,7 +28,10 @@ Help-link Loaded Short description ~ |package-cfilter| No Filtering quickfix/location list |package-justify| No Justify text |package-nohlsearch| No Automatically run :nohlsearch +|package-spellfile| Yes Install spellfile if missing |package-termdebug| No Debug inside Nvim with gdb +|package-tohtml| No Convert buffer to html, syntax included +|package-undotree| No Interactive textual undotree |pi_gzip.txt| Yes Reading and writing compressed files |pi_msgpack.txt| No msgpack utilities |pi_paren.txt| Yes Highlight matching parens @@ -37,9 +40,6 @@ Help-link Loaded Short description ~ |pi_tar.txt| Yes Tar file explorer |pi_tutor.txt| Yes Interactive tutorial |pi_zip.txt| Yes Zip archive explorer -|spellfile.lua| Yes Install spellfile if missing -|tohtml| Yes Convert buffer to html, syntax included -|undotree-plugin| No Interactive textual undotree ============================================================================== Builtin plugin: difftool *difftool* @@ -183,7 +183,7 @@ trim_trailing_whitespace *editorconfig.trim_trailing_whitespace* ============================================================================== -Builtin plugin: spellfile *spellfile.lua* +Builtin plugin: spellfile *package-spellfile* Asks the user to download missing spellfiles. The spellfile is written to `stdpath('data') .. 'site/spell'` or the first writable directory in the @@ -233,7 +233,7 @@ get({lang}) *spellfile.get()* ============================================================================== -Builtin plugin: tohtml *tohtml* +Builtin plugin: tohtml *package-tohtml* :[range]TOhtml {file} *:TOhtml* @@ -270,7 +270,7 @@ tohtml({winid}, {opt}) *tohtml.tohtml()* ============================================================================== -Builtin plugin: undotree *undotree-plugin* +Builtin plugin: undotree *package-undotree* open({opts}) *undotree.open()* Open a window that displays a textual representation of the |undo-tree|, diff --git a/runtime/doc/spell.txt b/runtime/doc/spell.txt index adfc849522..807615cf73 100644 --- a/runtime/doc/spell.txt +++ b/runtime/doc/spell.txt @@ -635,7 +635,7 @@ words that were generated from that .spl file. SPELL FILE MISSING *spell-SpellFileMissing* If a spell file is missing, the user is asked whether to download it. See -|spellfile.lua|. +|package-spellfile|. *E797* Note that the SpellFileMissing autocommand must not change or destroy the diff --git a/runtime/doc/undo.txt b/runtime/doc/undo.txt index cff7247ae2..60220c0271 100644 --- a/runtime/doc/undo.txt +++ b/runtime/doc/undo.txt @@ -134,7 +134,7 @@ Above we only discussed one line of undo/redo. But it is also possible to branch off. This happens when you undo a few changes and then make a new change. The undone changes become a branch. You can go to that branch with the following commands. The undo-tree of a file can be visualized and -interactively applied using |undotree-plugin|. +interactively applied using |:Undotree|. This is explained in the user manual: |usr_32.txt|. diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt index 29fdc6c6e4..57e739e3fb 100644 --- a/runtime/doc/various.txt +++ b/runtime/doc/various.txt @@ -105,6 +105,9 @@ gx Opens the current filepath, URL (decided by ||, 'isfname'), or |LSP| "documentLink" at cursor using the system default handler. + In |help| files, gx treats help tags as + https://neovim.io/doc/user/ URLs. + Mapped to |vim.ui.open()|. *v_gx* diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index f88971abc4..177f765739 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -97,8 +97,8 @@ Defaults *defaults* *nvim-defaults* - |man.lua| plugin is enabled, so |:Man| is available by default. - |matchit| plugin is enabled. To disable it in your config: >vim :let loaded_matchit = 1 -- |spellfile.lua| plugin is enabled, spellfiles are installed by default if - missing. +- |package-spellfile| plugin is enabled, spellfiles are installed by default + if missing. - |g:vimsyn_embed| defaults to "l" to enable Lua highlighting @@ -749,7 +749,7 @@ Editor: - *cscope* support was removed in favour of plugin-based solutions such as: https://github.com/dhananjaylatkar/cscope_maps.nvim - *popup-window* : Use |floating-windows| instead. -- *spellfile.vim* : Replaced by |spellfile.lua|. +- *spellfile.vim* : Replaced by |package-spellfile|. - *textprop* : Use |extmarks| instead. Eval: diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt index 36538ab11a..51f003ec3d 100644 --- a/runtime/doc/vimfn.txt +++ b/runtime/doc/vimfn.txt @@ -10650,7 +10650,7 @@ string({expr}) *string()* parsed back with |eval()|. {expr} type result ~ - String "string" + String `'string'` Number 123 Float 123.123456 or 1.123456e8 or `str2float('inf')` diff --git a/runtime/example_init.lua b/runtime/example_init.lua index e4c0b016ed..3ebe6f7dc7 100644 --- a/runtime/example_init.lua +++ b/runtime/example_init.lua @@ -101,7 +101,7 @@ vim.pack.add({ 'https://github.com/lewis6991/gitsigns.nvim', }) -require('fzf-lua').setup({ fzf_colors = true }) +require('fzf-lua').setup { fzf_colors = true } require('mini.completion').setup {} require('quicker').setup {} require('gitsigns').setup {} diff --git a/runtime/lua/vim/_core/editor.lua b/runtime/lua/vim/_core/editor.lua index 46ada5b9ab..bfc5e318fc 100644 --- a/runtime/lua/vim/_core/editor.lua +++ b/runtime/lua/vim/_core/editor.lua @@ -510,9 +510,8 @@ end --- Defers calling {fn} until {timeout} ms passes. --- ---- Use to do a one-shot timer that calls {fn} ---- Note: The {fn} is |vim.schedule()|d automatically, so API functions are ---- safe to call. +--- Use to do a one-shot timer that calls {fn}. +--- Note: The {fn} is |schedule|d automatically, so API functions are safe to call. ---@param fn function Callback to call once `timeout` expires ---@param timeout integer Number of milliseconds to wait before calling `fn` ---@return uv.uv_timer_t timer luv timer object diff --git a/runtime/lua/vim/_core/ui2.lua b/runtime/lua/vim/_core/ui2.lua index d308c226b3..ca9e38f059 100644 --- a/runtime/lua/vim/_core/ui2.lua +++ b/runtime/lua/vim/_core/ui2.lua @@ -32,7 +32,7 @@ --- --- There are four special windows/buffers for presenting messages and cmdline: --- - "cmd": Cmdline. Also used for 'showcmd', 'showmode', 'ruler', and messages by default. ---- - "msg": Message window, shows fleeting messages useful for 'cmdheight' == 0. +--- - "msg": Message window, shows ephemeral messages useful for 'cmdheight' == 0. --- - "pager": Pager window, shows |:messages| and certain messages that are never "collapsed". --- - "dialog": Dialog window, shows modal prompts that expect user input. --- diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 2eec5633bc..ccaa6192aa 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -9,17 +9,21 @@ error('Cannot require a meta file') vim.api = {} +--- WARNING: This feature is experimental/unstable. +--- --- @param buffer integer --- @param keys boolean --- @param dot boolean --- @return string function vim.api.nvim__buf_debug_extmarks(buffer, keys, dot) end +--- WARNING: This feature is experimental/unstable. +--- --- @param buffer integer --- @return table function vim.api.nvim__buf_stats(buffer) end ---- EXPERIMENTAL: this API may change in the future. +--- WARNING: This feature is experimental/unstable. --- --- Sets info for the completion item at the given index. If the info text was shown in a window, --- returns the window and buffer ids, or empty dict if not shown. @@ -32,9 +36,13 @@ function vim.api.nvim__buf_stats(buffer) end --- - bufnr: (number) buffer id in floating window function vim.api.nvim__complete_set(index, opts) end +--- WARNING: This feature is experimental/unstable. +--- --- @return string function vim.api.nvim__get_lib_dir() end +--- WARNING: This feature is experimental/unstable. +--- --- Find files in runtime directories --- --- @param pat string[] pattern of files to search for @@ -43,6 +51,8 @@ function vim.api.nvim__get_lib_dir() end --- @return string[] # list of absolute paths to the found files function vim.api.nvim__get_runtime(pat, all, opts) end +--- WARNING: This feature is experimental/unstable. +--- --- Returns object given as argument. --- --- This API function is used for testing. One should not rely on its presence @@ -52,6 +62,8 @@ function vim.api.nvim__get_runtime(pat, all, opts) end --- @return any # its argument. function vim.api.nvim__id(obj) end +--- WARNING: This feature is experimental/unstable. +--- --- Returns array given as argument. --- --- This API function is used for testing. One should not rely on its presence @@ -61,6 +73,8 @@ function vim.api.nvim__id(obj) end --- @return any[] # its argument. function vim.api.nvim__id_array(arr) end +--- WARNING: This feature is experimental/unstable. +--- --- Returns dict given as argument. --- --- This API function is used for testing. One should not rely on its presence @@ -70,6 +84,8 @@ function vim.api.nvim__id_array(arr) end --- @return table # its argument. function vim.api.nvim__id_dict(dct) end +--- WARNING: This feature is experimental/unstable. +--- --- Returns floating-point value given as argument. --- --- This API function is used for testing. One should not rely on its presence @@ -79,6 +95,8 @@ function vim.api.nvim__id_dict(dct) end --- @return number # its argument. function vim.api.nvim__id_float(flt) end +--- WARNING: This feature is experimental/unstable. +--- --- NB: if your UI doesn't use hlstate, this will not return hlstate first time. --- @param grid integer --- @param row integer @@ -86,11 +104,13 @@ function vim.api.nvim__id_float(flt) end --- @return any[] function vim.api.nvim__inspect_cell(grid, row, col) end +--- WARNING: This feature is experimental/unstable. +--- --- For testing. The condition in schar_cache_clear_if_full is hard to --- reach, so this function can be used to force a cache clear in a test. function vim.api.nvim__invalidate_glyph_cache() end ---- EXPERIMENTAL: this API will change in the future. +--- WARNING: This feature is experimental/unstable. --- --- Get the properties for namespace --- @@ -98,7 +118,7 @@ function vim.api.nvim__invalidate_glyph_cache() end --- @return vim.api.keyset.ns_opts # Map defining the namespace properties, see |nvim__ns_set()| function vim.api.nvim__ns_get(ns_id) end ---- EXPERIMENTAL: this API will change in the future. +--- WARNING: This feature is experimental/unstable. --- --- Set some properties for namespace --- @@ -107,7 +127,7 @@ function vim.api.nvim__ns_get(ns_id) end --- - wins: a list of windows to be scoped in function vim.api.nvim__ns_set(ns_id, opts) end ---- EXPERIMENTAL: this API may change in the future. +--- WARNING: This feature is experimental/unstable. --- --- Instruct Nvim to redraw various components. --- @@ -134,17 +154,25 @@ function vim.api.nvim__ns_set(ns_id, opts) end --- - tabline: Redraw the 'tabline'. function vim.api.nvim__redraw(opts) end +--- WARNING: This feature is experimental/unstable. +--- --- @return any[] function vim.api.nvim__runtime_inspect() end +--- WARNING: This feature is experimental/unstable. +--- --- @param path string function vim.api.nvim__screenshot(path) end +--- WARNING: This feature is experimental/unstable. +--- --- Gets internal stats. --- --- @return table # Map of various internal stats. function vim.api.nvim__stats() end +--- WARNING: This feature is experimental/unstable. +--- --- @param str string --- @return any function vim.api.nvim__unpack(str) end diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index da762aa878..4b919b7eef 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -965,10 +965,7 @@ vim.go.cb = vim.go.clipboard --- used. The command-line will cover the last line of the screen when --- shown. --- ---- 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. +--- WARNING: `cmdheight=0` is EXPERIMENTAL. Works better with `ui2` enabled. --- --- @type integer vim.o.cmdheight = 1 @@ -3807,7 +3804,6 @@ vim.go.js = vim.go.joinspaces --- the action occurred. --- --- clean Remove unloaded buffers from the jumplist. ---- EXPERIMENTAL: this flag may change in the future. --- --- @type string vim.o.jumpoptions = "clean" @@ -6527,7 +6523,7 @@ vim.bo.spf = vim.bo.spellfile --- encoding is used, Vim doesn't check it. --- How the related spell files are found is explained here: `spell-load`. --- ---- If the `spellfile.lua` plugin is active and you use a language name +--- If the `package-spellfile` plugin is active and you use a language name --- for which Vim cannot find the .spl file in 'runtimepath' the plugin --- will ask you if you want to download the file. --- diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index d10687cc26..1d3412d20a 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -9717,7 +9717,7 @@ function vim.fn.stridx(haystack, needle, start) end --- parsed back with |eval()|. --- --- {expr} type result ~ ---- String "string" +--- String `'string'` --- Number 123 --- Float 123.123456 or 1.123456e8 or --- `str2float('inf')` diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua index 9a956b7b51..11da76b58f 100644 --- a/runtime/lua/vim/lsp.lua +++ b/runtime/lua/vim/lsp.lua @@ -1163,7 +1163,7 @@ end --- Also return uninitialized clients. --- @field package _uninitialized? boolean ---- Get active clients. +--- Gets active clients. --- ---@since 12 --- diff --git a/runtime/lua/vim/net.lua b/runtime/lua/vim/net.lua index ad9e39e35c..b678b0bb2c 100644 --- a/runtime/lua/vim/net.lua +++ b/runtime/lua/vim/net.lua @@ -20,11 +20,8 @@ local M = {} ---The HTTP body of the request ---@field body string ---- Makes an HTTP GET request to the given URL (asynchronous). ---- ---- This function is asynchronous (non-blocking), returning immediately and ---- passing the response object to the optional `on_response` handler on ---- completion. +--- Makes an HTTP GET request to the given URL, asynchronously passing the result to the specified +--- `on_response`, `outpath` or `outbuf`. --- --- Examples: --- ```lua diff --git a/src/gen/gen_eval_files.lua b/src/gen/gen_eval_files.lua index 928c218e7d..dce5322921 100755 --- a/src/gen/gen_eval_files.lua +++ b/src/gen/gen_eval_files.lua @@ -272,6 +272,12 @@ local function render_api_meta(_f, fun, write) write('--- @deprecated') end + local internal = vim.startswith(fun.name, 'nvim__') + if internal or (fun.since and tonumber(fun.since) == 0) then + write('--- WARNING: This feature is experimental/unstable.') + write('---') + end + local desc = fun.desc if desc then write(util.prefix_lines('--- ', norm_text(desc))) diff --git a/src/gen/gen_vimdoc.lua b/src/gen/gen_vimdoc.lua index 2db5b85b1d..9ad60580a6 100755 --- a/src/gen/gen_vimdoc.lua +++ b/src/gen/gen_vimdoc.lua @@ -431,10 +431,10 @@ local config = { }, files = { 'runtime/lua/editorconfig.lua', + 'runtime/lua/nvim/spellfile.lua', 'runtime/pack/dist/opt/nvim.tohtml/lua/tohtml.lua', 'runtime/pack/dist/opt/nvim.undotree/lua/undotree.lua', 'runtime/pack/dist/opt/nvim.difftool/lua/difftool.lua', - 'runtime/lua/nvim/spellfile.lua', }, fn_xform = function(fun) if fun.module == 'editorconfig' then @@ -451,10 +451,8 @@ local config = { end, helptag_fmt = function(name) name = name:lower() - if name == 'spellfile' then - name = 'spellfile.lua' - elseif name == 'undotree' then - name = 'undotree-plugin' + if vim.tbl_contains({ 'spellfile', 'tohtml', 'undotree' }, name) then + name = ('package-%s'):format(name) end return name end, @@ -801,18 +799,19 @@ local function render_fun(fun, classes, cfg) return end + local internal = vim.startswith(fun.name, 'nvim__') local ret = {} --- @type string[] table.insert(ret, render_fun_header(fun, cfg)) table.insert(ret, '\n') - if fun.since then - local since = assert(tonumber(fun.since), 'invalid @since on ' .. fun.name) + if internal or fun.since then + local since = assert(tonumber(fun.since or (internal and 0)), 'invalid @since on ' .. fun.name) local nvim_api = nvim_api_info() _ = nvim_api -- Disable prerelease "WARNING" doc, in preparation for for upcoming release. if - since == 0 --[[or (nvim_api.prerelease and since == nvim_api.level)]] + internal or since == 0 --[[or (nvim_api.prerelease and since == nvim_api.level)]] then -- Experimental = (since==0 or current prerelease) local s = 'WARNING: This feature is experimental/unstable.' diff --git a/src/nvim/api/extmark.c b/src/nvim/api/extmark.c index c3bb23fbb2..b6618c9694 100644 --- a/src/nvim/api/extmark.c +++ b/src/nvim/api/extmark.c @@ -1244,8 +1244,6 @@ String nvim__buf_debug_extmarks(Buffer buffer, Boolean keys, Boolean dot, Error return mt_inspect(buf->b_marktree, keys, dot); } -/// EXPERIMENTAL: this API will change in the future. -/// /// Set some properties for namespace /// /// @param ns_id Namespace @@ -1321,8 +1319,6 @@ void nvim__ns_set(Integer ns_id, Dict(ns_opts) *opts, Error *err) } } -/// EXPERIMENTAL: this API will change in the future. -/// /// Get the properties for namespace /// /// @param ns_id Namespace diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 2975fec2e7..8460e62652 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -534,8 +534,6 @@ Object nvim_exec_lua(String code, Array args, Arena *arena, Error *err) return nlua_exec(code, NULL, args, kRetObject, arena, err); } -/// EXPERIMENTAL: this API may change or be removed in the future. -/// /// Like |nvim_exec_lua()|, but can be called during |api-fast| contexts. /// /// Execute Lua code. Parameters (if any) are available as `...` inside the @@ -2302,8 +2300,6 @@ DictAs(eval_statusline_ret) nvim_eval_statusline(String str, Dict(eval_statuslin return result; } -/// EXPERIMENTAL: this API may change in the future. -/// /// Sets info for the completion item at the given index. If the info text was shown in a window, /// returns the window and buffer ids, or empty dict if not shown. /// @@ -2361,8 +2357,6 @@ static void redraw_status(win_T *wp, Dict(redraw) *opts, bool *flush) } } -/// EXPERIMENTAL: this API may change in the future. -/// /// Instruct Nvim to redraw various components. /// /// @see |:redraw| diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua index 21a08452bb..f8539b907d 100644 --- a/src/nvim/eval.lua +++ b/src/nvim/eval.lua @@ -11713,7 +11713,7 @@ M.funcs = { parsed back with |eval()|. {expr} type result ~ - String "string" + String `'string'` Number 123 Float 123.123456 or 1.123456e8 or `str2float('inf')` diff --git a/src/nvim/options.lua b/src/nvim/options.lua index 8b91e27308..bdc33dd5fc 100644 --- a/src/nvim/options.lua +++ b/src/nvim/options.lua @@ -1356,10 +1356,7 @@ local options = { used. The command-line will cover the last line of the screen when shown. - 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. + WARNING: `cmdheight=0` is EXPERIMENTAL. Works better with |ui2| enabled. ]=], full_name = 'cmdheight', redraw = { 'all_windows' }, @@ -5010,7 +5007,6 @@ local options = { the action occurred. clean Remove unloaded buffers from the jumplist. - EXPERIMENTAL: this flag may change in the future. ]=], full_name = 'jumpoptions', list = 'onecomma', @@ -8533,7 +8529,7 @@ local options = { encoding is used, Vim doesn't check it. How the related spell files are found is explained here: |spell-load|. - If the |spellfile.lua| plugin is active and you use a language name + If the |package-spellfile| plugin is active and you use a language name for which Vim cannot find the .spl file in 'runtimepath' the plugin will ask you if you want to download the file. diff --git a/test/functional/treesitter/highlight_spec.lua b/test/functional/treesitter/highlight_spec.lua index b45150ba2b..87b7c272be 100644 --- a/test/functional/treesitter/highlight_spec.lua +++ b/test/functional/treesitter/highlight_spec.lua @@ -980,10 +980,9 @@ describe('treesitter highlighting (C)', function() end) it('#35575', function() - clear() -- Window size is 14x14, and first string literal ends at byte 14 -- See: https://github.com/neovim/neovim/pull/35587 - screen = Screen.new(14, 15) + screen:try_resize(14, 15) exec_lua(function() local line = 'A a="\240\157\158\140\240\157\158\140" "aaaaaaaaaaaaaaaaaaaaaaaa";'