Fix all documentation warnings reported by LDoc.

14 files changed, 140 insertions, 122 deletions

diff --git a/src/luarocks/build/make.lua b/src/luarocks/build/make.lua
index 80c0d4f4..c4b21578 100644
--- a/src/luarocks/build/make.lua
+++ b/src/luarocks/build/make.lua
@@ -7,6 +7,9 @@ local util = require("luarocks.util")
 local cfg = require("luarocks.cfg")
 
 --- Call "make" with given target and variables
+-- @param make_cmd string: the make command to be used (typically
+-- configured through variables.MAKE in the config files, or
+-- the appropriate platform-specific default).
 -- @param pass boolean: If true, run make; if false, do nothing.
 -- @param target string: The make target; an empty string indicates 
 -- the default target.
diff --git a/src/luarocks/deps.lua b/src/luarocks/deps.lua
index 227ce9f8..9cc9f2c4 100644
--- a/src/luarocks/deps.lua
+++ b/src/luarocks/deps.lua
@@ -606,12 +606,15 @@ end
 --- Recursively scan dependencies, to build a transitive closure of all
 -- dependent packages.
 -- @param results table: The results table being built.
+-- @param missing table: The table of missing dependencies being recursively built.
+-- @param manifest table: The manifest table containing dependencies.
 -- @param name string: Package name.
 -- @param version string: Package version.
 -- @return (table, table): The results and a table of missing dependencies.
 function scan_deps(results, missing, manifest, name, version)
    assert(type(results) == "table")
    assert(type(missing) == "table")
+   assert(type(manifest) == "table")
    assert(type(name) == "string")
    assert(type(version) == "string")
 
diff --git a/src/luarocks/fetch.lua b/src/luarocks/fetch.lua
index 80ca4400..bdb448c7 100644
--- a/src/luarocks/fetch.lua
+++ b/src/luarocks/fetch.lua
@@ -122,7 +122,7 @@ end
 
 --- Back-end function that actually loads the local rockspec.
 -- Performs some validation and postprocessing of the rockspec contents.
--- @param file string: The local filename of the rockspec file.
+-- @param filename string: The local filename of the rockspec file.
 -- @return table or (nil, string): A table representing the rockspec
 -- or nil followed by an error message.
 function load_local_rockspec(filename)
diff --git a/src/luarocks/fs/lua.lua b/src/luarocks/fs/lua.lua
index 2a176259..29b71c55 100644
--- a/src/luarocks/fs/lua.lua
+++ b/src/luarocks/fs/lua.lua
@@ -595,6 +595,7 @@ end
 
 --- Apply a patch.
 -- @param patchname string: The filename of the patch.
+-- @param patchdata string or nil: The actual patch as a string.
 function apply_patch(patchname, patchdata)
    local p, all_ok = patch.read_patch(patchname, patchdata)
    if not all_ok then
diff --git a/src/luarocks/fs/unix/tools.lua b/src/luarocks/fs/unix/tools.lua
index 73f01518..5e91439b 100644
--- a/src/luarocks/fs/unix/tools.lua
+++ b/src/luarocks/fs/unix/tools.lua
@@ -11,7 +11,7 @@ local dir_stack = {}
 local vars = cfg.variables
 
 --- Run the given command.
--- The command is executed in the current directory in the dir stack.
+-- The command is executed in the current directory in the directory stack.
 -- @param cmd string: No quoting/escaping is applied to the command.
 -- @return boolean: true if command succeeds (status code 0), false
 -- otherwise.
@@ -25,26 +25,26 @@ function execute_string(cmd)
 end
 
 --- Obtain current directory.
--- Uses the module's internal dir stack.
+-- Uses the module's internal directory stack.
 -- @return string: the absolute pathname of the current directory.
 function current_dir()
    local pipe = io.popen(vars.PWD)
    local current = pipe:read("*l")
    pipe:close()
-   for _, d in ipairs(dir_stack) do
-      current = fs.absolute_name(d, current)
+   for _, directory in ipairs(dir_stack) do
+      current = fs.absolute_name(directory, current)
    end
    return current
 end
 
 --- Change the current directory.
--- Uses the module's internal dir stack. This does not have exact
+-- Uses the module's internal directory stack. This does not have exact
 -- semantics of chdir, as it does not handle errors the same way,
 -- but works well for our purposes for now.
--- @param d string: The directory to switch to.
-function change_dir(d)
-   assert(type(d) == "string")
-   table.insert(dir_stack, d)
+-- @param directory string: The directory to switch to.
+function change_dir(directory)
+   assert(type(directory) == "string")
+   table.insert(dir_stack, directory)
 end
 
 --- Change directory to root.
@@ -54,44 +54,44 @@ function change_dir_to_root()
    table.insert(dir_stack, "/")
 end
 
---- Change working directory to the previous in the dir stack.
+--- Change working directory to the previous in the directory stack.
 function pop_dir()
-   local d = table.remove(dir_stack)
-   return d ~= nil
+   local directory = table.remove(dir_stack)
+   return directory ~= nil
 end
 
 --- Create a directory if it does not already exist.
 -- If any of the higher levels in the path name does not exist
 -- too, they are created as well.
--- @param d string: pathname of directory to create.
+-- @param directory string: pathname of directory to create.
 -- @return boolean: true on success, false on failure.
-function make_dir(d)
-   assert(d)
-   return fs.execute(vars.MKDIR.." -p", d)
+function make_dir(directory)
+   assert(directory)
+   return fs.execute(vars.MKDIR.." -p", directory)
 end
 
 --- Remove a directory if it is empty.
 -- Does not return errors (for example, if directory is not empty or
 -- if already does not exist)
--- @param dir string: pathname of directory to remove.
-function remove_dir_if_empty(d)
-   assert(d)
-   fs.execute_string(vars.RMDIR.." "..fs.Q(d).." 1> /dev/null 2> /dev/null")
+-- @param directory string: pathname of directory to remove.
+function remove_dir_if_empty(directory)
+   assert(directory)
+   fs.execute_string(vars.RMDIR.." "..fs.Q(directory).." 1> /dev/null 2> /dev/null")
 end
 
 --- Remove a directory if it is empty.
 -- Does not return errors (for example, if directory is not empty or
 -- if already does not exist)
--- @param dir string: pathname of directory to remove.
-function remove_dir_tree_if_empty(d)
-   assert(d)
-   fs.execute_string(vars.RMDIR.." -p "..fs.Q(d).." 1> /dev/null 2> /dev/null")
+-- @param directory string: pathname of directory to remove.
+function remove_dir_tree_if_empty(directory)
+   assert(directory)
+   fs.execute_string(vars.RMDIR.." -p "..fs.Q(directory).." 1> /dev/null 2> /dev/null")
 end
 
 --- Copy a file.
 -- @param src string: Pathname of source
 -- @param dest string: Pathname of destination
--- @param perms string or nil: Permissions for destination file,
+-- @param perm string or nil: Permissions for destination file,
 -- @return boolean or (boolean, string): true on success, false on failure,
 -- plus an error message.
 function copy(src, dest, perm)
@@ -205,7 +205,7 @@ function exists(file)
    return fs.execute(vars.TEST, "-r", file)
 end
 
---- Test is file/dir is writable.
+--- Test is file/directory is writable.
 -- @param file string: filename to test
 -- @return boolean: true if file exists, false otherwise.
 function is_writable(file)
diff --git a/src/luarocks/fs/win32/tools.lua b/src/luarocks/fs/win32/tools.lua
index 5b7634cf..2ad84371 100644
--- a/src/luarocks/fs/win32/tools.lua
+++ b/src/luarocks/fs/win32/tools.lua
@@ -42,14 +42,14 @@ function exists(file)
 end
 
 --- Obtain current directory.
--- Uses the module's internal dir stack.
+-- Uses the module's internal directory stack.
 -- @return string: the absolute pathname of the current directory.
 function current_dir()
    local pipe = io.popen(vars.PWD)
    local current = pipe:read("*l")
    pipe:close()
-   for _, d in ipairs(dir_stack) do
-      current = fs.absolute_name(d, current)
+   for _, directory in ipairs(dir_stack) do
+      current = fs.absolute_name(directory, current)
    end
    return current
 end
@@ -82,13 +82,13 @@ function get_md5(file)
 end
 
 --- Change the current directory.
--- Uses the module's internal dir stack. This does not have exact
+-- Uses the module's internal directory stack. This does not have exact
 -- semantics of chdir, as it does not handle errors the same way,
 -- but works well for our purposes for now.
--- @param d string: The directory to switch to.
-function change_dir(d)
-   assert(type(d) == "string")
-   table.insert(dir_stack, d)
+-- @param directory string: The directory to switch to.
+function change_dir(directory)
+   assert(type(directory) == "string")
+   table.insert(dir_stack, directory)
 end
 
 --- Change directory to root.
@@ -98,14 +98,14 @@ function change_dir_to_root()
    table.insert(dir_stack, "/")
 end
 
---- Change working directory to the previous in the dir stack.
+--- Change working directory to the previous in the directory stack.
 function pop_dir()
-   local d = table.remove(dir_stack)
-   return d ~= nil
+   local directory = table.remove(dir_stack)
+   return directory ~= nil
 end
 
 --- Run the given command.
--- The command is executed in the current directory in the dir stack.
+-- The command is executed in the current directory in the directory stack.
 -- @param cmd string: No quoting/escaping is applied to the command.
 -- @return boolean: true if command succeeds (status code 0), false
 -- otherwise.
@@ -128,30 +128,30 @@ end
 --- Create a directory if it does not already exist.
 -- If any of the higher levels in the path name does not exist
 -- too, they are created as well.
--- @param d string: pathname of directory to create.
+-- @param directory string: pathname of directory to create.
 -- @return boolean: true on success, false on failure.
-function make_dir(d)
-   assert(d)
-   fs.execute(vars.MKDIR.." "..fs.Q(d).." 1> NUL 2> NUL")
+function make_dir(directory)
+   assert(directory)
+   fs.execute(vars.MKDIR.." "..fs.Q(directory).." 1> NUL 2> NUL")
    return 1
 end
 
 --- Remove a directory if it is empty.
 -- Does not return errors (for example, if directory is not empty or
 -- if already does not exist)
--- @param d string: pathname of directory to remove.
-function remove_dir_if_empty(d)
-   assert(d)
-   fs.execute_string(vars.RMDIR.." "..fs.Q(d).." 1> NUL 2> NUL")
+-- @param directory string: pathname of directory to remove.
+function remove_dir_if_empty(directory)
+   assert(directory)
+   fs.execute_string(vars.RMDIR.." "..fs.Q(directory).." 1> NUL 2> NUL")
 end
 
 --- Remove a directory if it is empty.
 -- Does not return errors (for example, if directory is not empty or
 -- if already does not exist)
--- @param dir string: pathname of directory to remove.
-function remove_dir_tree_if_empty(d)
-   assert(d)
-   fs.execute_string(vars.RMDIR.." "..fs.Q(d).." 1> NUL 2> NUL")
+-- @param directory string: pathname of directory to remove.
+function remove_dir_tree_if_empty(directory)
+   assert(directory)
+   fs.execute_string(vars.RMDIR.." "..fs.Q(directory).." 1> NUL 2> NUL")
 end
 
 --- Copy a file.
diff --git a/src/luarocks/manif.lua b/src/luarocks/manif.lua
index 44a21f91..9cacc3ff 100644
--- a/src/luarocks/manif.lua
+++ b/src/luarocks/manif.lua
@@ -172,12 +172,11 @@ local function sort_package_matching_table(tbl)
    end
 end
 
---- Process the dependencies of a package to determine its dependency
--- chain for loading modules.
--- @param name string: Package name.
--- @param version string: Package version.
--- @return (table, table): A table listing dependencies as string-string pairs
--- of names and versions, and a similar table of missing dependencies.
+--- Process the dependencies of a manifest table to determine its dependency
+-- chains for loading modules. The manifest dependencies information is filled
+-- and any dependency inconsistencies or missing dependencies are reported to
+-- standard error.
+-- @param manifest table: a manifest table.
 local function update_dependencies(manifest)
    for pkg, versions in pairs(manifest.repository) do
       for version, repos in pairs(versions) do
@@ -205,6 +204,8 @@ end
 --- Store search results in a manifest table.
 -- @param results table: The search results as returned by search.disk_search.
 -- @param manifest table: A manifest table (must contain repository, modules, commands tables).
+-- It will be altered to include the search results.
+-- @return boolean or (nil, string): true in case of success, or nil followed by an error message.
 local function store_results(results, manifest)
    assert(type(results) == "table")
    assert(type(manifest) == "table")
diff --git a/src/luarocks/manif_core.lua b/src/luarocks/manif_core.lua
index 2e1a9518..40f16898 100644
--- a/src/luarocks/manif_core.lua
+++ b/src/luarocks/manif_core.lua
@@ -15,6 +15,7 @@ manifest_cache = {}
 -- and stores it in the manifest cache.
 -- @param file string: The local filename of the manifest file.
 -- @param repo_url string: The repository identifier.
+-- @param quick boolean: If given, skips type checking.
 function manifest_loader(file, repo_url, quick)
    local manifest, err = persist.load_into_table(file)
    if not manifest then
diff --git a/src/luarocks/path.lua b/src/luarocks/path.lua
index 9b7f6bc7..99127235 100644
--- a/src/luarocks/path.lua
+++ b/src/luarocks/path.lua
@@ -25,12 +25,12 @@ function rockspec_name_from_rock(rock_name)
    return base_name:match("(.*)%.[^.]*.rock") .. ".rockspec"
 end
 
-function rocks_dir(repo)
-   if type(repo) == "string" then
-      return dir.path(repo, "lib", "luarocks", "rocks")
+function rocks_dir(tree)
+   if type(tree) == "string" then
+      return dir.path(tree, "lib", "luarocks", "rocks")
    else
-      assert(type(repo) == "table")
-      return repo.rocks_dir or dir.path(repo.root, "lib", "luarocks", "rocks")
+      assert(type(tree) == "table")
+      return tree.rocks_dir or dir.path(tree.root, "lib", "luarocks", "rocks")
    end
 end
 
@@ -41,156 +41,156 @@ function root_dir(rocks_dir)
    return rocks_dir:match("(.*)" .. suffix .. "$")
 end
 
-function deploy_bin_dir(repo)
-   if type(repo) == "string" then
-      return dir.path(repo, "bin")
+function deploy_bin_dir(tree)
+   if type(tree) == "string" then
+      return dir.path(tree, "bin")
    else
-      assert(type(repo) == "table")
-      return repo.bin_dir or dir.path(repo.root, "bin")
+      assert(type(tree) == "table")
+      return tree.bin_dir or dir.path(tree.root, "bin")
    end
 end
 
-function deploy_lua_dir(repo)
-   if type(repo) == "string" then
-      return dir.path(repo, cfg.lua_modules_path)
+function deploy_lua_dir(tree)
+   if type(tree) == "string" then
+      return dir.path(tree, cfg.lua_modules_path)
    else
-      assert(type(repo) == "table")
-      return repo.lua_dir or dir.path(repo.root, cfg.lua_modules_path)
+      assert(type(tree) == "table")
+      return tree.lua_dir or dir.path(tree.root, cfg.lua_modules_path)
    end
 end
 
-function deploy_lib_dir(repo)
-   if type(repo) == "string" then
-      return dir.path(repo, cfg.lib_modules_path)
+function deploy_lib_dir(tree)
+   if type(tree) == "string" then
+      return dir.path(tree, cfg.lib_modules_path)
    else
-      assert(type(repo) == "table")
-      return repo.lib_dir or dir.path(repo.root, cfg.lib_modules_path)
+      assert(type(tree) == "table")
+      return tree.lib_dir or dir.path(tree.root, cfg.lib_modules_path)
    end
 end
 
-function manifest_file(repo)
-   if type(repo) == "string" then
-      return dir.path(repo, "lib", "luarocks", "rocks", "manifest")
+function manifest_file(tree)
+   if type(tree) == "string" then
+      return dir.path(tree, "lib", "luarocks", "rocks", "manifest")
    else
-      assert(type(repo) == "table")
-      return (repo.rocks_dir and dir.path(repo.rocks_dir, "manifest")) or dir.path(repo.root, "lib", "luarocks", "rocks", "manifest")
+      assert(type(tree) == "table")
+      return (tree.rocks_dir and dir.path(tree.rocks_dir, "manifest")) or dir.path(tree.root, "lib", "luarocks", "rocks", "manifest")
    end
 end
 
---- Get the repository directory for all versions of a package.
+--- Get the directory for all versions of a package in a tree.
 -- @param name string: The package name. 
 -- @return string: The resulting path -- does not guarantee that
--- @param rocks_dir string or nil: If given, specifies the local repository to use.
+-- @param tree string or nil: If given, specifies the local tree to use.
 -- the package (and by extension, the path) exists.
-function versions_dir(name, repo)
+function versions_dir(name, tree)
    assert(type(name) == "string")
-   repo = repo or cfg.root_dir
-   return dir.path(rocks_dir(repo), name)
+   tree = tree or cfg.root_dir
+   return dir.path(rocks_dir(tree), name)
 end
 
 --- Get the local installation directory (prefix) for a package.
 -- @param name string: The package name. 
 -- @param version string: The package version.
--- @param rocks_dir string or nil: If given, specifies the local repository to use.
+-- @param tree string or nil: If given, specifies the local tree to use.
 -- @return string: The resulting path -- does not guarantee that
 -- the package (and by extension, the path) exists.
-function install_dir(name, version, repo)
+function install_dir(name, version, tree)
    assert(type(name) == "string")
    assert(type(version) == "string")
-   repo = repo or cfg.root_dir
-   return dir.path(rocks_dir(repo), name, version)
+   tree = tree or cfg.root_dir
+   return dir.path(rocks_dir(tree), name, version)
 end
 
 --- Get the local filename of the rockspec of an installed rock.
 -- @param name string: The package name. 
 -- @param version string: The package version.
--- @param rocks_dir string or nil: If given, specifies the local repository to use.
+-- @param tree string or nil: If given, specifies the local tree to use.
 -- @return string: The resulting path -- does not guarantee that
 -- the package (and by extension, the file) exists.
-function rockspec_file(name, version, repo)
+function rockspec_file(name, version, tree)
    assert(type(name) == "string")
    assert(type(version) == "string")
-   repo = repo or cfg.root_dir
-   return dir.path(rocks_dir(repo), name, version, name.."-"..version..".rockspec")
+   tree = tree or cfg.root_dir
+   return dir.path(rocks_dir(tree), name, version, name.."-"..version..".rockspec")
 end
 
 --- Get the local filename of the rock_manifest file of an installed rock.
 -- @param name string: The package name. 
 -- @param version string: The package version.
--- @param rocks_dir string or nil: If given, specifies the local repository to use.
+-- @param tree string or nil: If given, specifies the local tree to use.
 -- @return string: The resulting path -- does not guarantee that
 -- the package (and by extension, the file) exists.
-function rock_manifest_file(name, version, repo)
+function rock_manifest_file(name, version, tree)
    assert(type(name) == "string")
    assert(type(version) == "string")
-   repo = repo or cfg.root_dir
-   return dir.path(rocks_dir(repo), name, version, "rock_manifest")
+   tree = tree or cfg.root_dir
+   return dir.path(rocks_dir(tree), name, version, "rock_manifest")
 end
 
 --- Get the local installation directory for C libraries of a package.
 -- @param name string: The package name. 
 -- @param version string: The package version.
--- @param rocks_dir string or nil: If given, specifies the local repository to use.
+-- @param tree string or nil: If given, specifies the local tree to use.
 -- @return string: The resulting path -- does not guarantee that
 -- the package (and by extension, the path) exists.
-function lib_dir(name, version, repo)
+function lib_dir(name, version, tree)
    assert(type(name) == "string")
    assert(type(version) == "string")
-   repo = repo or cfg.root_dir
-   return dir.path(rocks_dir(repo), name, version, "lib")
+   tree = tree or cfg.root_dir
+   return dir.path(rocks_dir(tree), name, version, "lib")
 end
 
 --- Get the local installation directory for Lua modules of a package.
 -- @param name string: The package name. 
 -- @param version string: The package version.
--- @param rocks_dir string or nil: If given, specifies the local repository to use.
+-- @param tree string or nil: If given, specifies the local tree to use.
 -- @return string: The resulting path -- does not guarantee that
 -- the package (and by extension, the path) exists.
-function lua_dir(name, version, repo)
+function lua_dir(name, version, tree)
    assert(type(name) == "string")
    assert(type(version) == "string")
-   repo = repo or cfg.root_dir
-   return dir.path(rocks_dir(repo), name, version, "lua")
+   tree = tree or cfg.root_dir
+   return dir.path(rocks_dir(tree), name, version, "lua")
 end
 
 --- Get the local installation directory for documentation of a package.
 -- @param name string: The package name. 
 -- @param version string: The package version.
--- @param rocks_dir string or nil: If given, specifies the local repository to use.
+-- @param tree string or nil: If given, specifies the local tree to use.
 -- @return string: The resulting path -- does not guarantee that
 -- the package (and by extension, the path) exists.
-function doc_dir(name, version, repo)
+function doc_dir(name, version, tree)
    assert(type(name) == "string")
    assert(type(version) == "string")
-   repo = repo or cfg.root_dir
-   return dir.path(rocks_dir(repo), name, version, "doc")
+   tree = tree or cfg.root_dir
+   return dir.path(rocks_dir(tree), name, version, "doc")
 end
 
 --- Get the local installation directory for configuration files of a package.
 -- @param name string: The package name. 
 -- @param version string: The package version.
--- @param rocks_dir string or nil: If given, specifies the local repository to use.
+-- @param tree string or nil: If given, specifies the local tree to use.
 -- @return string: The resulting path -- does not guarantee that
 -- the package (and by extension, the path) exists.
-function conf_dir(name, version, repo)
+function conf_dir(name, version, tree)
    assert(type(name) == "string")
    assert(type(version) == "string")
-   repo = repo or cfg.root_dir
-   return dir.path(rocks_dir(repo), name, version, "conf")
+   tree = tree or cfg.root_dir
+   return dir.path(rocks_dir(tree), name, version, "conf")
 end
 
 --- Get the local installation directory for command-line scripts
 -- of a package.
 -- @param name string: The package name. 
 -- @param version string: The package version.
--- @param rocks_dir string or nil: If given, specifies the local repository to use.
+-- @param tree string or nil: If given, specifies the local tree to use.
 -- @return string: The resulting path -- does not guarantee that
 -- the package (and by extension, the path) exists.
-function bin_dir(name, version, repo)
+function bin_dir(name, version, tree)
    assert(type(name) == "string")
    assert(type(version) == "string")
-   repo = repo or cfg.root_dir
-   return dir.path(rocks_dir(repo), name, version, "bin")
+   tree = tree or cfg.root_dir
+   return dir.path(rocks_dir(tree), name, version, "bin")
 end
 
 --- Extract name, version and arch of a rock filename,
diff --git a/src/luarocks/persist.lua b/src/luarocks/persist.lua
index c809b51c..91c28a32 100644
--- a/src/luarocks/persist.lua
+++ b/src/luarocks/persist.lua
@@ -34,6 +34,7 @@ end
 -- are keys (tables are handled recursively).
 -- @param out userdata: a file object, open for writing.
 -- @param tbl table: the table to be written.
+-- @param level number: the indentation level
 local function write_table(out, tbl, level)
    out:write("{")
    local sep = "\n"
diff --git a/src/luarocks/search.lua b/src/luarocks/search.lua
index 127bba19..9671d15b 100644
--- a/src/luarocks/search.lua
+++ b/src/luarocks/search.lua
@@ -331,8 +331,8 @@ end
 -- user possibilities if it couldn't narrow down a single match.
 -- @param action function: A function that takes a .src.rock or
 -- .rockspec URL as a parameter.
--- @string name string: A rock name
--- @string version string or nil: A version number may also be given.
+-- @param name string: A rock name
+-- @param version string or nil: A version number may also be given.
 -- @return The result of the action function, or nil and an error message. 
 function act_on_src_or_rockspec(action, name, version)
    assert(type(action) == "function")
diff --git a/src/luarocks/type_check.lua b/src/luarocks/type_check.lua
index 57340675..282198f6 100644
--- a/src/luarocks/type_check.lua
+++ b/src/luarocks/type_check.lua
@@ -156,6 +156,9 @@ local type_check_table
 -- @param item any: The object being checked.
 -- @param expected any: The reference object. In case of a table,
 -- its is structured as a type reference table.
+-- @param context string: A string indicating the "context" where the
+-- error occurred (such as the name of the table the item is a part of),
+-- to be used by error messages.
 -- @return boolean or (nil, string): true if type checking
 -- succeeded, or nil and an error message if it failed.
 -- @see type_check_table
@@ -205,6 +208,9 @@ end
 -- @param tbl table: The table to be type checked.
 -- @param types table: The reference table, containing
 -- values for recognized fields in the checked table.
+-- @param context string: A string indicating the "context" where the
+-- error occurred (such as the name of the table the item is a part of),
+-- to be used by error messages.
 -- @return boolean or (nil, string): true if type checking
 -- succeeded, or nil and an error message if it failed.
 type_check_table = function(tbl, types, context)
diff --git a/src/luarocks/unpack.lua b/src/luarocks/unpack.lua
index dacafa31..6ea7353d 100644
--- a/src/luarocks/unpack.lua
+++ b/src/luarocks/unpack.lua
@@ -45,6 +45,8 @@ end
 --- Load a .rock file to the given directory and unpack it inside it.
 -- @param rock_file string: The URL for a .rock file.
 -- @param dir_name string: The directory where to unpack.
+-- @param kind string: the kind of rock file, as in the second-level
+-- extension in the rock filename (eg. "src", "all", "linux-x86")
 -- @return table or (nil, string): the loaded rockspec table or 
 -- nil and an error message.
 local function unpack_rock(rock_file, dir_name, kind)
diff --git a/src/luarocks/util.lua b/src/luarocks/util.lua
index 24c2accb..4495c024 100644
--- a/src/luarocks/util.lua
+++ b/src/luarocks/util.lua
@@ -26,7 +26,7 @@ end
 
 --- Unschedule a function.
 -- This is useful for cancelling a rollback of a completed operation.
--- @param table: The token representing the scheduled function that was
+-- @param item table: The token representing the scheduled function that was
 -- returned from the schedule_function call.
 function remove_scheduled_function(item)
    for k, v in pairs(scheduled_functions) do