docs: misc, dev-api-fast, $XDG_STATE_HOME #35138

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.
+
 
 ==============================================================================
 

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
 

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.

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,
+	5. $VIMRUNTIME, for files distributed with Nvim.
-	   viewdir, undodir, etc.
-	   Given by `stdpath("state")`.  |$XDG_STATE_HOME|
-	6. $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).
 

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
+filetype one.  The scripts in $VIMRUNTIME/scripts are global ones, the
-plugins are in $VIMRUNTIME/ftplugin.
+filetype plugins are in $VIMRUNTIME/ftplugin.
 
 
 USING A FILETYPE PLUGIN					*ftplugin-name*

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:
+text: >
-	the first line ~
+	the first line
-	the second line ~
+	the second line
 
 This is entered by typing <Tab>, some text, <Enter>, <Tab> and more text.
    The 'autoindent' option inserts indents automatically: >

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
+		state        String  Session state: storage for backupdir,
-				     drafts, swap, undo, |shada|.
+				     file drafts, |shada|, swap, undo, 'viewdir'.
 
 		Example: >vim
 			echo stdpath("config")

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,
+--- 5. $VIMRUNTIME, for files distributed with Nvim.
----    viewdir, undodir, etc.
----    Given by `stdpath("state")`.  `$XDG_STATE_HOME`
---- 6. $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).
 ---

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
+--- state        String  Session state: storage for backupdir,
----          drafts, swap, undo, |shada|.
+---          file drafts, |shada|, swap, undo, 'viewdir'.
 ---
 --- Example: >vim
 ---   echo stdpath("config")

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
+      state        String  Session state: storage for backupdir,
-      		     drafts, swap, undo, |shada|.
+      		     file drafts, |shada|, swap, undo, 'viewdir'.
 
       Example: >vim
       	echo stdpath("config")

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
+/// Gets a number item from a dictionary.
-///
-/// Returns 0 if the entry does not exist.
 ///
 /// @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.
+/// Gets a number item from a dictionary, or a given default value.
-///
-/// Returns "def" if the entry doesn't exist.
 ///
 /// @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
 {

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,
+        5. $VIMRUNTIME, for files distributed with Nvim.
-           viewdir, undodir, etc.
-           Given by `stdpath("state")`.  |$XDG_STATE_HOME|
-        6. $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).
 

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')

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')