From 0d32e5ba3087d7fca48b9d01e533010588625558 Mon Sep 17 00:00:00 2001
From: Diomendius <42310725+Diomendius@users.noreply.github.com>
Date: Thu, 26 Aug 2021 21:39:29 +1200
Subject: [PATCH 1/2] docs(lua): fix, clarify Lua require() docs

Corrects lua.txt help file to say that require() searches runtimepath
and loads the first module found, not the last.

Also adds additional clarification on require() and module search order.

Closes #15480
---
 runtime/doc/lua.txt | 34 +++++++++++++++++++++++++---------
 1 file changed, 25 insertions(+), 9 deletions(-)

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index cc70c7b2fd..5b054b8261 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -21,19 +21,35 @@ Nvim includes a "standard library" |lua-stdlib| for Lua.  It complements the
 be used from Lua code. A good overview of using Lua in neovim is given by
 https://github.com/nanotee/nvim-lua-guide.
 
-Module conflicts are resolved by "last wins".  For example if both of these
-are on 'runtimepath':
-    runtime/lua/foo.lua
-    ~/.config/nvim/lua/foo.lua
-then `require('foo')` loads "~/.config/nvim/lua/foo.lua", and
-"runtime/lua/foo.lua" is not used.  See |lua-require| to understand how Nvim
-finds and loads Lua modules.  The conventions are similar to those of
-Vimscript |plugin|s, with some extra features.  See |lua-require-example| for
-a walkthrough.
+The |:source| and |:runtime| commands can run Lua scripts as well as Vim
+scripts.  Lua modules can be loaded with `require('name')`, which
+conventionally returns a table but can return any value.
+
+See |lua-require| for details on how Nvim finds and loads Lua modules.
+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
+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 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:
+    foo/lua/mod.lua
+    bar/lua/mod.lua
+    foo/lua/mod/init.lua
+    bar/lua/mod/init.lua
+
                                                         *lua-package-path*
 Nvim automatically adjusts `package.path` and `package.cpath` according to
 effective 'runtimepath' value.  Adjustment happens whenever 'runtimepath' is

From 89270346f986a47ee73a8edae51e3269de608668 Mon Sep 17 00:00:00 2001
From: Diomendius <42310725+Diomendius@users.noreply.github.com>
Date: Mon, 22 Nov 2021 00:11:32 +1300
Subject: [PATCH 2/2] 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.
---
 runtime/doc/lua.txt | 21 +++++++++++++++------
 1 file 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