Commit: runtime(doc): clarify vim9 script autoload mechanism

runtime(doc): clarify vim9 script autoload mechanism

Commit: https://github.com/vim/vim/commit/935fa240ea276f7bf361be87a1b0aa3ea15fd33a
Author: Ubaldo Tiberi <[email protected]>
Date:   Mon Jul 27 18:40:49 2026 +0000

    runtime(doc): clarify vim9 script autoload mechanism
    
    closes: https://github.com/vim/vim/issues/20833
    
    Signed-off-by: Ubaldo Tiberi <[email protected]>
    Signed-off-by: Christian Brabandt <[email protected]>

diff --git a/runtime/doc/usr_52.txt b/runtime/doc/usr_52.txt
index f59e74b4e..b34a80d49 100644
--- a/runtime/doc/usr_52.txt
+++ b/runtime/doc/usr_52.txt
@@ -1,4 +1,4 @@
-*usr_52.txt*	For Vim version 9.2.  Last change: 2026 Feb 14
+*usr_52.txt*	For Vim version 9.2.  Last change: 2026 Jul 27
 
 
 		     VIM USER MANUAL	by Bram Moolenaar
@@ -136,47 +136,83 @@ prefix that is very unlikely to be used elsewhere.  For example, if you have a
 ==============================================================================
 *52.2*	Autoloading
 
-After splitting your large script into pieces, all the lines will still be
-loaded and executed the moment the script is used.  Every `import` loads the
-imported script to find the items defined there.  Although that is good for
-finding errors early, it also takes time.  Which is wasted if the
-functionality is not often used.
+After splitting a large script into pieces, an imported script is loaded and
+executed at the moment the importing script is sourced.  Every |:import| loads
+the imported script to find the items defined there.  However, if an imported
+script is large, then the startup time may become noticeably slower, but on
+the other hand if there are errors they will be detected at import time.
 
-Instead of having `import` load the script immediately, it can be postponed
-until needed.  Using the example above, only one change needs to be made in
-the plugin/theplugin.vim script: >
+To avoid long startup times, the loading of an imported script may be deferred
+until it is actually needed.  This is done with the `autoload` keyword. Using
+the example above, only one change is needed in `plugin/theplugin.vim`:
+>
 	import autoload "../lib/getmessage.vim"
-
+<
 Nothing in the rest of the script needs to change.  However, the types will
-not be checked.  Not even the existence of the GetMessage() function is
-checked until it is used.  You will have to decide what is more important for
-your script: fast startup or getting errors early.  You can also add the
-"autoload" argument later, after you have checked everything works.
+not be checked, and "../lib/getmessage.vim" is not loaded at import time; Vim
+only verifies that the file exists and is readable.  Not even the existence of
+the GetMessage() function is checked until it is used.  As a result, errors in
+the "getmessage.vim" script are detected only at runtime.
 
+You will have to decide what is more important for your script: fast startup
+or getting errors early.
 
-AUTOLOAD DIRECTORY
+A practical strategy is to omit the `autoload` keyword during development and
+debugging so that errors are reported immediately, then add it back before
+distributing your plugin to improve startup performance.
 
-Another form is to use autoload with a script name that is not an absolute or
-relative path: >
-	import autoload "monthlib.vim"
 
-This will search for the script "monthlib.vim" in the autoload directories of
-'runtimepath'.  With Unix one of the directories often is "~/.vim/autoload".
-It will also search under 'packpath', under "start".
+AUTOLOAD DIRECTORIES
 
-The main advantage of this is that this script can be easily shared with other
-scripts.  You do need to make sure that the script name is unique, since Vim
-will search all the "autoload" directories in 'runtimepath', and if you are
-using several plugins with a plugin manager, it may add a directory to
-'runtimepath', each of which might have an "autoload" directory.
+Another way to lazily load scripts is to `import autoload` a script without
+specifying any relative or absolute path, like in the following example: >
 
-Without autoload: >
+	import autoload "monthlib.vim"
+<
+Vim searches for the script in the "autoload" directories under 'runtimepath'.
+This means that the script must reside in an "autoload" folder.  On Unix
+systems, one such directory is often `~/.vim/autoload`.  It will also search
+under 'packpath', under "start".
+
+When a script is imported this way, its exported symbols are referenced
+through a global autoload namespace rather than remaining local to the
+importing script.
+
+Since Vim searches every "autoload" directory in 'runtimepath', choose a
+unique script name.  Plugin managers often add multiple directories to
+'runtimepath', each of which may contain an "autoload" directory.
+
+The two forms of `import autoload` are summarized as follows:
+
+- `import autoload "foo.vim"`
+  Vim searches 'runtimepath' for the script.  Because such scripts must reside
+  under an "autoload" directory, exported symbols are available through the
+  global autoload namespace.
+
+- `import autoload "/some/path/foo.vim"`
+  If the resolved path falls under an "autoload" directory, exported symbols
+  are likewise in the global autoload namespace; otherwise they remain local
+  to the importing script.
+
+The main advantage of accessing symbols through the global autoload namespace
+is that the script can be easily imported by other scripts, and symbols can
+be used straight away.  However, this has some drawbacks when reloading a
+script, see |vim9-reload| for more info.
+
+When symbols are in script-local scope, sharing them across scripts is more
+involved and there is no general rule: the right approach depends on the
+plugin layout.
+
+Finally, when a script is imported without `autoload` and without path, like
+the following example: >
 	import "monthlib.vim"
-
+<
 Vim will search for the script "monthlib.vim" in the import directories of
-'runtimepath'.  Note that in this case adding or removing "autoload" changes
-where the script is found.  With a relative or absolute path the location does
-not change.
+'runtimepath'.
+
+In this case, adding or removing the `autoload` keyword changes where Vim
+searches for the script.  When a relative or absolute path is used, then the
+location does not change.
 
 ==============================================================================
 *52.3*	Autoloading without import/export

-- 
-- 
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php

--- 
You received this message because you are subscribed to the Google Groups "vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].
To view this discussion visit https://groups.google.com/d/msgid/vim_dev/E1woQYV-00H56z-FN%40256bit.org.