commit 960b33a9d810a8f70423bbab614d024e0468f115
parent 1d40f677760d3fbaaaac6292841f2f5426bf83bd
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Sun, 17 Aug 2025 23:45:40 -0400
docs: misc, dev-api-fast, $XDG_STATE_HOME #35138
Diffstat:
14 files changed, 49 insertions(+), 38 deletions(-)
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 <Tab> 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 <Tab>, some text, <Enter>, <Tab> and more text.
The 'autoindent' option inserts indents automatically: >
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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')
