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,
-	   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).
 

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*

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: >

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

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

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