docs(lua): further improve Lua require() docs

Change docs to reflect recent changes to require() search order and add
info on `.` in module names and search order for shared library modules.

1 files changed, 15 insertions, 6 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 5b054b8261..d9a820913d 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -32,9 +32,13 @@ See |lua-require-example| for an example of how to write and use a module.
 IMPORTING LUA MODULES                                   *lua-require*
 
 Modules are searched for under the directories specified in 'runtimepath', in
-the order they appear.  For a module `foo`, each directory is searched for
-`lua/foo.lua`, then the entire list is searched again for `lua/foo/init.lua`,
-then paths specified by `package.path` and `package.cpath`.  The first script
+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`.
 
@@ -43,12 +47,17 @@ module, with subsequent calls returning the cached value without searching for
 or executing any script.  For further details on `require()`, see the Lua
 documentation at https://www.lua.org/manual/5.1/manual.html#pdf-require.
 
-For example, if 'runtimepath' is "foo,bar", `require('mod')` searches these
-paths in order and the first script found is used:
+For example, if 'runtimepath' is `foo,bar` and `package.cpath` was
+`./?.so;./?.dll` at startup, `require('mod')` searches these paths in order
+and loads the first module found:
     foo/lua/mod.lua
-    bar/lua/mod.lua
     foo/lua/mod/init.lua
+    bar/lua/mod.lua
     bar/lua/mod/init.lua
+    foo/lua/mod.so
+    foo/lua/mod.dll
+    bar/lua/mod.so
+    bar/lua/mod.dll
 
                                                         *lua-package-path*
 Nvim automatically adjusts `package.path` and `package.cpath` according to