docs: faq, lua packages #33183

Problem:
- `health#check()` seems to have been removed for a while, but `:h faq`
  still refers to it.
- `news-0.11.txt` doesn't mention #33044

6 files changed, 22 insertions, 71 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index eba4bc9562..da438622d9 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -3773,8 +3773,8 @@ nvim_create_autocmd({event}, {opts})                   *nvim_create_autocmd()*
                  • callback (function|string) optional: Lua function (or
                    Vimscript function name, if string) called when the
                    event(s) is triggered. Lua callback can return a truthy
-                   value (not `false` or `nil`) to delete the autocommand.
-                   Receives one argument, a table with these keys:
+                   value (not `false` or `nil`) to delete the autocommand, and
+                   receives one argument, a table with these keys:
                                                                   *event-args*
                    • id: (number) autocommand id
                    • event: (string) name of the triggered event
diff --git a/runtime/doc/faq.txt b/runtime/doc/faq.txt
index a9a7b1768e..b41a99a3f8 100644
--- a/runtime/doc/faq.txt
+++ b/runtime/doc/faq.txt
@@ -205,17 +205,11 @@ Other hints:
 
 :CHECKHEALTH REPORTS E5009: INVALID $VIMRUNTIME ~
 
-This means `health#check()` couldn't load, which suggests that |$VIMRUNTIME|
-or 'runtimepath' is broken.
+This means |$VIMRUNTIME| or 'runtimepath' is broken.
 
 - |$VIMRUNTIME| must point to Nvim's runtime files, not Vim's.
 - The |$VIMRUNTIME| directory contents should be readable by the current user.
 - Verify that `:echo &runtimepath` contains the $VIMRUNTIME path.
-- Check the output of: >vim
-
-    :call health#check()
-    :verbose func health#check
-<
 
 NEOVIM CAN'T FIND ITS RUNTIME ~
 
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index ceb8184eef..be118cf790 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -188,15 +188,19 @@ Examples: >lua
 ==============================================================================
 IMPORTING LUA MODULES                                        *lua-module-load*
 
-Modules are searched for under the directories specified in 'runtimepath', in
-the order they appear.  Any "." in the module name is treated as a directory
-separator when searching.  For a module `foo.bar`, each directory is searched
-for `lua/foo/bar.lua`, then `lua/foo/bar/init.lua`.  If no files are found,
-the directories are searched again for a shared library with a name matching
-`lua/foo/bar.?`, where `?` is a list of suffixes (such as `so` or `dll`) derived from
-the initial value of |package.cpath|. If still no files are found, Nvim falls
-back to Lua's default search mechanism. The first script found is run and
-`require()` returns the value returned by the script if any, else `true`.
+Modules are searched for under the directories specified in 'runtimepath' and
+|packages-runtimepath|, in the order they appear in the output of this command
+>vim
+	:echo nvim_list_runtime_paths()
+<
+Any "." in the module name is treated as a directory separator when searching.
+For a module `foo.bar`, each directory is searched for `lua/foo/bar.lua`, then
+`lua/foo/bar/init.lua`.  If no files are found, the directories are searched
+again for a shared library with a name matching `lua/foo/bar.?`, where `?` is
+a list of suffixes (such as `so` or `dll`) derived from the initial value of
+|package.cpath|. If still no files are found, Nvim falls back to Lua's default
+search mechanism. The first script found is run and `require()` returns the
+value returned by the script if any, else `true`.
 
 The return value is cached after the first call to `require()` for each module,
 with subsequent calls returning the cached value without searching for, or
@@ -214,56 +218,9 @@ and loads the first module found ("first wins"): >
     bar/lua/mod.so
     bar/lua/mod.dll
 <
-                                                        *lua-package-path*
-Nvim automatically adjusts |package.path| and |package.cpath| according to the
-effective 'runtimepath' value. Adjustment happens whenever 'runtimepath' is
-changed. `package.path` is adjusted by simply appending `/lua/?.lua` and
-`/lua/?/init.lua` to each directory from 'runtimepath' (`/` is actually the
-first character of `package.config`).
-
-Similarly to |package.path|, modified directories from 'runtimepath' are also
-added to |package.cpath|. In this case, instead of appending `/lua/?.lua` and
-`/lua/?/init.lua` to each runtimepath, all unique `?`-containing suffixes of
-the existing |package.cpath| are used. Example:
-
-- 1. Given that
-   - 'runtimepath' contains `/foo/bar,/xxx;yyy/baz,/abc`;
-   - initial |package.cpath| (defined at compile-time or derived from
-     `$LUA_CPATH` / `$LUA_INIT`) contains `./?.so;/def/ghi/a?d/j/g.elf;/def/?.so`.
-- 2. It finds `?`-containing suffixes `/?.so`, `/a?d/j/g.elf` and `/?.so`, in
-     order: parts of the path starting from the first path component containing
-     question mark and preceding path separator.
-- 3. The suffix of `/def/?.so`, namely `/?.so` is not unique, as it’s the same
-     as the suffix of the first path from |package.path| (i.e. `./?.so`). Which
-     leaves `/?.so` and `/a?d/j/g.elf`, in this order.
-- 4. 'runtimepath' has three paths: `/foo/bar`, `/xxx;yyy/baz` and `/abc`. The
-     second one contains a semicolon which is a paths separator so it is out,
-     leaving only `/foo/bar` and `/abc`, in order.
-- 5. The cartesian product of paths from 4. and suffixes from 3. is taken,
-     giving four variants. In each variant a `/lua` path segment is inserted
-     between path and suffix, leaving:
-     - `/foo/bar/lua/?.so`
-     - `/foo/bar/lua/a?d/j/g.elf`
-     - `/abc/lua/?.so`
-     - `/abc/lua/a?d/j/g.elf`
-- 6. New paths are prepended to the original |package.cpath|.
-
-The result will look like this: >
-
-    /foo/bar,/xxx;yyy/baz,/abc ('runtimepath')
-    × ./?.so;/def/ghi/a?d/j/g.elf;/def/?.so (package.cpath)
-    = /foo/bar/lua/?.so;/foo/bar/lua/a?d/j/g.elf;/abc/lua/?.so;/abc/lua/a?d/j/g.elf;./?.so;/def/ghi/a?d/j/g.elf;/def/?.so
-
 Note:
 
-- To track 'runtimepath' updates, paths added at previous update are
-  remembered and removed at the next update, while all paths derived from the
-  new 'runtimepath' are prepended as described above. This allows removing
-  paths when path is removed from 'runtimepath', adding paths when they are
-  added and reordering |package.path|/|package.cpath| content if 'runtimepath'
-  was reordered.
-
-- Although adjustments happen automatically, Nvim does not track current
+- Although 'runtimepath' is tracked, Nvim does not track current
   values of |package.path| or |package.cpath|. If you happen to delete some
   paths from there you can set 'runtimepath' to trigger an update: >vim
       let &runtimepath = &runtimepath
diff --git a/runtime/doc/news-0.11.txt b/runtime/doc/news-0.11.txt
index f934456c3a..88804b0c12 100644
--- a/runtime/doc/news-0.11.txt
+++ b/runtime/doc/news-0.11.txt
@@ -288,7 +288,7 @@ LUA
 
 • Command-line completions for: `vim.g`, `vim.t`, `vim.w`, `vim.b`, `vim.v`,
   `vim.o`, `vim.wo`, `vim.bo`, `vim.opt`, `vim.opt_local`, `vim.opt_global`,
-  and `vim.fn`.
+  `vim.env` and `vim.fn`.
 • Documentation for |lua-bit|.
 • |gf| in Lua buffers can go to module in same repo, |runtime-search-path| and
   |package.path|.
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index e7ad91132d..5e684ab408 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -939,8 +939,8 @@ function vim.api.nvim_create_augroup(name, opts) end
 --- - desc (string) optional: description (for documentation and troubleshooting).
 --- - callback (function|string) optional: Lua function (or Vimscript function name, if
 --- string) called when the event(s) is triggered. Lua callback can return a truthy
---- value (not `false` or `nil`) to delete the autocommand. Receives one argument,
---- a table with these keys: [event-args]()
+--- value (not `false` or `nil`) to delete the autocommand, and receives one argument, a
+--- table with these keys: [event-args]()
 ---     - id: (number) autocommand id
 ---     - event: (string) name of the triggered event `autocmd-events`
 ---     - group: (number|nil) autocommand group id, if any
diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c
index 1e33b0b62a..7c98736289 100644
--- a/src/nvim/api/autocmd.c
+++ b/src/nvim/api/autocmd.c
@@ -369,8 +369,8 @@ cleanup:
 ///             - desc (string) optional: description (for documentation and troubleshooting).
 ///             - callback (function|string) optional: Lua function (or Vimscript function name, if
 ///             string) called when the event(s) is triggered. Lua callback can return a truthy
-///             value (not `false` or `nil`) to delete the autocommand. Receives one argument,
-///             a table with these keys: [event-args]()
+///             value (not `false` or `nil`) to delete the autocommand, and receives one argument, a
+///             table with these keys: [event-args]()
 ///                 - id: (number) autocommand id
 ///                 - event: (string) name of the triggered event |autocmd-events|
 ///                 - group: (number|nil) autocommand group id, if any