Fix docs for path.which_i and some of its users

It actually accepts file name of the module as in
manifest.repository[package][version].modules[module], not the
module name.

src/luarocks/loader.lua

@@ -126,17 +126,17 @@ end
 
 --- Search for a module in the rocks trees
 -- @param module string: module name (eg. "socket.core")
--- @param filter_module_name function(string, string, string, string, number):
--- a function that takes the module name (eg "socket.core"), the rock name
+-- @param filter_file_name function(string, string, string, string, number):
+-- a function that takes the module file name (eg "socket/core.so"), the rock name
 -- (eg "luasocket"), the version (eg "2.0.2-1"), the path of the rocks tree
 -- (eg "/usr/local"), and the numeric index of the matching entry, so the
 -- filter function can know if the matching module was the first entry or not.
 -- @return string, string, string, (string or table):
 -- * name of the rock containing the module (eg. "luasocket")
 -- * version of the rock (eg. "2.0.2-1")
--- * name of the module (eg. "socket.core", or "socket.core_2_0_2" if file is stored versioned).
+-- * return value of filter_file_name
 -- * tree of the module (string or table in `rocks_trees` format)
-local function select_module(module, filter_module_name)
+local function select_module(module, filter_file_name)
    --assert(type(module) == "string")
    --assert(type(filter_module_name) == "function")
 
@@ -150,16 +150,16 @@ local function select_module(module, filter_module_name)
       if entries then
          for i, entry in ipairs(entries) do
             local name, version = entry:match("^([^/]*)/(.*)$")
-            local module_name = tree.manifest.repository[name][version][1].modules[module]
-            if type(module_name) ~= "string" then
+            local file_name = tree.manifest.repository[name][version][1].modules[module]
+            if type(file_name) ~= "string" then
                error("Invalid data in manifest file for module "..tostring(module).." (invalid data for "..tostring(name).." "..tostring(version)..")")
             end
-            module_name = filter_module_name(module_name, name, version, tree.tree, i)
+            file_name = filter_file_name(file_name, name, version, tree.tree, i)
             if loader.context[name] == version then
-               return name, version, module_name
+               return name, version, file_name
             end
             version = deps.parse_version(version)
-            table.insert(providers, {name = name, version = version, module_name = module_name, tree = tree})
+            table.insert(providers, {name = name, version = version, module_name = file_name, tree = tree})
          end
       end
    end
@@ -180,21 +180,20 @@ end
 -- * tree of the module (string or table in `rocks_trees` format)
 local function pick_module(module)
    return
-      select_module(module, function(module_name, name, version, tree, i)
+      select_module(module, function(file_name, name, version, tree, i)
          if i > 1 then
-            module_name = path.versioned_name(module_name, "", name, version)
+            file_name = path.versioned_name(file_name, "", name, version)
          end
-         module_name = path.path_to_module(module_name)
-         return module_name
+         return path.path_to_module(file_name)
       end)
 end
 
 --- Return the pathname of the file that would be loaded for a module.
 -- @param module string: module name (eg. "socket.core")
 -- @return string: filename of the module (eg. "/usr/local/lib/lua/5.1/socket/core.so")
 function loader.which(module)
-   local name, version, module_name = select_module(module, path.which_i)
-   return module_name
+   local _, _, file_name = select_module(module, path.which_i)
+   return file_name
 end
 
 --- Package loader for LuaRocks support.

src/luarocks/path.lua

@@ -342,44 +342,45 @@ end
 local is_src_extension = { [".lua"] = true, [".tl"] = true, [".tld"] = true, [".moon"] = true }
 
 --- Return the pathname of the file that would be loaded for a module, indexed.
--- @param module_name string: module name (eg. "socket.core")
+-- @param file_name string: module file name as in manifest (eg. "socket/core.so")
 -- @param name string: name of the package (eg. "luasocket")
 -- @param version string: version number (eg. "2.0.2-1")
 -- @param tree string: repository path (eg. "/usr/local")
 -- @param i number: the index, 1 if version is the current default, > 1 otherwise.
 -- This is done this way for use by select_module in luarocks.loader.
 -- @return string: filename of the module (eg. "/usr/local/lib/lua/5.1/socket/core.so")
-function path.which_i(module_name, name, version, tree, i)
+function path.which_i(file_name, name, version, tree, i)
    local deploy_dir
-   local extension = module_name:match("%.[a-z]+$")
+   local extension = file_name:match("%.[a-z]+$")
    if is_src_extension[extension] then
       deploy_dir = path.deploy_lua_dir(tree)
-      module_name = dir.path(deploy_dir, module_name)
+      file_name = dir.path(deploy_dir, file_name)
    else
       deploy_dir = path.deploy_lib_dir(tree)
-      module_name = dir.path(deploy_dir, module_name)
+      file_name = dir.path(deploy_dir, file_name)
    end
    if i > 1 then
-      module_name = path.versioned_name(module_name, deploy_dir, name, version)
+      file_name = path.versioned_name(file_name, deploy_dir, name, version)
    end
-   return module_name
+   return file_name
 end
 
 --- Return the pathname of the file that would be loaded for a module, 
 -- returning the versioned pathname if given version is not the default version
 -- in the given manifest.
 -- @param module_name string: module name (eg. "socket.core")
+-- @param file_name string: module file name as in manifest (eg. "socket/core.so")
 -- @param name string: name of the package (eg. "luasocket")
 -- @param version string: version number (eg. "2.0.2-1")
 -- @param tree string: repository path (eg. "/usr/local")
 -- @param manifest table: the manifest table for the tree.
 -- @return string: filename of the module (eg. "/usr/local/lib/lua/5.1/socket/core.so")
-function path.which(module_name, filename, name, version, tree, manifest)
+function path.which(module_name, file_name, name, version, tree, manifest)
    local versions = manifest.modules[module_name]
    assert(versions)
    for i, name_version in ipairs(versions) do
       if name_version == name.."/"..version then
-         return path.which_i(filename, name, version, tree, i):gsub("//", "/")
+         return path.which_i(file_name, name, version, tree, i):gsub("//", "/")
       end
    end
    assert(false)