From 960b33a9d810a8f70423bbab614d024e0468f115 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 17 Aug 2025 23:45:40 -0400 Subject: [PATCH] docs: misc, dev-api-fast, $XDG_STATE_HOME #35138 --- runtime/doc/dev_arch.txt | 21 +++++++++++++++++++++ runtime/doc/news.txt | 1 + runtime/doc/nvim.txt | 4 +++- runtime/doc/options.txt | 7 ++----- runtime/doc/usr_05.txt | 6 +++--- runtime/doc/usr_25.txt | 6 +++--- runtime/doc/vimfn.txt | 4 ++-- runtime/lua/vim/_meta/options.lua | 7 ++----- runtime/lua/vim/_meta/vimfn.lua | 4 ++-- src/nvim/eval.lua | 4 ++-- src/nvim/eval/typval.c | 12 ++++-------- src/nvim/options.lua | 7 ++----- test/functional/ui/inccommand_spec.lua | 2 +- test/functional/ui/inccommand_user_spec.lua | 2 +- 14 files changed, 49 insertions(+), 38 deletions(-) diff --git a/runtime/doc/dev_arch.txt b/runtime/doc/dev_arch.txt index 2be6221117..97f22b57a8 100644 --- a/runtime/doc/dev_arch.txt +++ b/runtime/doc/dev_arch.txt @@ -53,6 +53,27 @@ Other references: - https://github.com/neovim/neovim/pull/21605 +============================================================================== +API + + *dev-api-fast* +API functions and Vimscript "eval" functions may be marked as |api-fast| which +means they are safe to call in Lua callbacks and other scenarios. A functions +CANNOT be marked as "fast" if could trigger `os_breakcheck()`, which may +"yield" the current execution and start a new execution of code not expecting +this: +- accidentally recursing into a function not expecting this. +- changing (global) state without restoring it before returning to the + "yielded" callsite. + +In practice, this means any code that could trigger `os_breakcheck()` cannot +be "fast". For example, commit 3940c435e405 fixed such a bug with +`nvim__get_runtime` by explicitly disallowing `os_breakcheck()` via the +`EW_NOBREAK` flag. + +Common examples of non-fast code: regexp matching, wildcard expansion, +expression evaluation. + ============================================================================== diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index cc7cd013ff..0dbd53918b 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -313,6 +313,7 @@ UI • "Error detected while processing:" changed to "Error in:". • "Error executing Lua:" changed to "Lua:". • 'busy' status is shown in default statusline with symbol ◐ +• Improved LSP signature help rendering. VIMSCRIPT diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt index 002563e111..7b36ab4127 100644 --- a/runtime/doc/nvim.txt +++ b/runtime/doc/nvim.txt @@ -63,7 +63,9 @@ Transitioning from Vim *nvim-from-vim* let &packpath = &runtimepath source ~/.vimrc -3. Restart Nvim, your existing Vim config will be loaded. +3. Restart Nvim, your existing Vim config will be loaded. >vim + + :restart See |provider-python| and |provider-clipboard| for additional software you might need to use some features. diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 348624629f..56c8a6b612 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -5140,12 +5140,9 @@ A jump table for the options with a short description can be found at |Q_op|. but are not part of the Nvim distribution. XDG_DATA_DIRS defaults to /usr/local/share/:/usr/share/, so system administrators are expected to install site plugins to /usr/share/nvim/site. - 5. Session state directory, for state data such as swap, backupdir, - viewdir, undodir, etc. - Given by `stdpath("state")`. |$XDG_STATE_HOME| - 6. $VIMRUNTIME, for files distributed with Nvim. + 5. $VIMRUNTIME, for files distributed with Nvim. *after-directory* - 7, 8, 9, 10. In after/ subdirectories of 1, 2, 3 and 4, with reverse + 6, 7, 8, 9. In after/ subdirectories of 1, 2, 3 and 4, with reverse ordering. This is for preferences to overrule or add to the distributed defaults or system-wide settings (rarely needed). diff --git a/runtime/doc/usr_05.txt b/runtime/doc/usr_05.txt index d3f1f9b479..147450aca6 100644 --- a/runtime/doc/usr_05.txt +++ b/runtime/doc/usr_05.txt @@ -291,7 +291,7 @@ GETTING A GLOBAL PLUGIN Where can you find plugins? - Some are always loaded, you can see them in the directory $VIMRUNTIME/plugin. -- Some come with Vim. You can find them in the directory $VIMRUNTIME/macros +- Some come with Vim. You can find them in the directory $VIMRUNTIME/scripts and its sub-directories and under $VIM/vimfiles/pack/dist/opt/. - Download from the net. There is a large collection on https://www.vim.org. - They are sometimes posted in a Vim maillist. @@ -338,8 +338,8 @@ GETTING A FILETYPE PLUGIN You can find them in the same places as the global plugins. Watch out if the type of file is mentioned, then you know if the plugin is a global or a -filetype one. The scripts in $VIMRUNTIME/macros are global ones, the filetype -plugins are in $VIMRUNTIME/ftplugin. +filetype one. The scripts in $VIMRUNTIME/scripts are global ones, the +filetype plugins are in $VIMRUNTIME/ftplugin. USING A FILETYPE PLUGIN *ftplugin-name* diff --git a/runtime/doc/usr_25.txt b/runtime/doc/usr_25.txt index 853a5025a1..a4c3d4ebbb 100644 --- a/runtime/doc/usr_25.txt +++ b/runtime/doc/usr_25.txt @@ -217,9 +217,9 @@ An alternative is to filter the text through an external program. Example: > Indents can be used to make text stand out from the rest. The example texts in this manual, for example, are indented by eight columns. You would normally enter this by typing at the start of each line. Take this -text: - the first line ~ - the second line ~ +text: > + the first line + the second line This is entered by typing , some text, , and more text. The 'autoindent' option inserts indents automatically: > diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt index 43beb8fd32..8cb9722cd6 100644 --- a/runtime/doc/vimfn.txt +++ b/runtime/doc/vimfn.txt @@ -10382,8 +10382,8 @@ stdpath({what}) *stdpath()* *E610 log String Logs directory (for use by plugins too). run String Run directory: temporary, local storage for sockets, named pipes, etc. - state String Session state directory: storage for file - drafts, swap, undo, |shada|. + state String Session state: storage for backupdir, + file drafts, |shada|, swap, undo, 'viewdir'. Example: >vim echo stdpath("config") diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 88a83c010e..5066db1ca9 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -5383,12 +5383,9 @@ vim.go.ruf = vim.go.rulerformat --- but are not part of the Nvim distribution. XDG_DATA_DIRS defaults --- to /usr/local/share/:/usr/share/, so system administrators are --- expected to install site plugins to /usr/share/nvim/site. ---- 5. Session state directory, for state data such as swap, backupdir, ---- viewdir, undodir, etc. ---- Given by `stdpath("state")`. `$XDG_STATE_HOME` ---- 6. $VIMRUNTIME, for files distributed with Nvim. +--- 5. $VIMRUNTIME, for files distributed with Nvim. --- *after-directory* ---- 7, 8, 9, 10. In after/ subdirectories of 1, 2, 3 and 4, with reverse +--- 6, 7, 8, 9. In after/ subdirectories of 1, 2, 3 and 4, with reverse --- ordering. This is for preferences to overrule or add to the --- distributed defaults or system-wide settings (rarely needed). --- diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index ac32434ebd..c1ac7c3fab 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -9473,8 +9473,8 @@ function vim.fn.stdioopen(opts) end --- log String Logs directory (for use by plugins too). --- run String Run directory: temporary, local storage --- for sockets, named pipes, etc. ---- state String Session state directory: storage for file ---- drafts, swap, undo, |shada|. +--- state String Session state: storage for backupdir, +--- file drafts, |shada|, swap, undo, 'viewdir'. --- --- Example: >vim --- echo stdpath("config") diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua index d237758e7a..87fd8beb22 100644 --- a/src/nvim/eval.lua +++ b/src/nvim/eval.lua @@ -11392,8 +11392,8 @@ M.funcs = { log String Logs directory (for use by plugins too). run String Run directory: temporary, local storage for sockets, named pipes, etc. - state String Session state directory: storage for file - drafts, swap, undo, |shada|. + state String Session state: storage for backupdir, + file drafts, |shada|, swap, undo, 'viewdir'. Example: >vim echo stdpath("config") diff --git a/src/nvim/eval/typval.c b/src/nvim/eval/typval.c index b560b889b2..87f2f5c584 100644 --- a/src/nvim/eval/typval.c +++ b/src/nvim/eval/typval.c @@ -2261,29 +2261,25 @@ int tv_dict_get_tv(dict_T *d, const char *const key, typval_T *rettv) return OK; } -/// Get a number item from a dictionary -/// -/// Returns 0 if the entry does not exist. +/// Gets a number item from a dictionary. /// /// @param[in] d Dictionary to get item from. /// @param[in] key Key to find in dictionary. /// -/// @return Dictionary item. +/// @return Number value, or 0 if the item does not exist. varnumber_T tv_dict_get_number(const dict_T *const d, const char *const key) FUNC_ATTR_PURE FUNC_ATTR_WARN_UNUSED_RESULT { return tv_dict_get_number_def(d, key, 0); } -/// Get a number item from a dictionary. -/// -/// Returns "def" if the entry doesn't exist. +/// Gets a number item from a dictionary, or a given default value. /// /// @param[in] d Dictionary to get item from. /// @param[in] key Key to find in dictionary. /// @param[in] def Default value. /// -/// @return Dictionary item. +/// @return Number value, or `def` value if the item does not exist. varnumber_T tv_dict_get_number_def(const dict_T *const d, const char *const key, const int def) FUNC_ATTR_PURE FUNC_ATTR_WARN_UNUSED_RESULT { diff --git a/src/nvim/options.lua b/src/nvim/options.lua index b90abd01d9..daa4de6d59 100644 --- a/src/nvim/options.lua +++ b/src/nvim/options.lua @@ -7088,12 +7088,9 @@ local options = { but are not part of the Nvim distribution. XDG_DATA_DIRS defaults to /usr/local/share/:/usr/share/, so system administrators are expected to install site plugins to /usr/share/nvim/site. - 5. Session state directory, for state data such as swap, backupdir, - viewdir, undodir, etc. - Given by `stdpath("state")`. |$XDG_STATE_HOME| - 6. $VIMRUNTIME, for files distributed with Nvim. + 5. $VIMRUNTIME, for files distributed with Nvim. *after-directory* - 7, 8, 9, 10. In after/ subdirectories of 1, 2, 3 and 4, with reverse + 6, 7, 8, 9. In after/ subdirectories of 1, 2, 3 and 4, with reverse ordering. This is for preferences to overrule or add to the distributed defaults or system-wide settings (rarely needed). diff --git a/test/functional/ui/inccommand_spec.lua b/test/functional/ui/inccommand_spec.lua index 7f976ca5a4..4cd9fefc4f 100644 --- a/test/functional/ui/inccommand_spec.lua +++ b/test/functional/ui/inccommand_spec.lua @@ -2938,7 +2938,7 @@ it("'inccommand' disables preview if preview buffer can't be created #27086", fu eq('nosplit', api.nvim_get_option_value('inccommand', {})) end) -it(':substitute with inccommand, does not show prompt during preview #11940', function() +it("'inccommand' :substitute preview skips input() prompt #11940", function() clear() local screen = Screen.new(30, 3) common_setup(screen, 'split', 'foo') diff --git a/test/functional/ui/inccommand_user_spec.lua b/test/functional/ui/inccommand_user_spec.lua index 167c879ad9..f425132911 100644 --- a/test/functional/ui/inccommand_user_spec.lua +++ b/test/functional/ui/inccommand_user_spec.lua @@ -393,7 +393,7 @@ describe("'inccommand' for user commands", function() ]]) end) - it('does not crash on ambiguous command #18825', function() + it('no crash on ambiguous command #18825', function() command('set inccommand=split') command('command Reply echo 1') feed(':R')