From 46825ad1dca508b70eeb77619c46c11afd46d5ec Mon Sep 17 00:00:00 2001 From: Hisham Muhammad Date: Wed, 21 Dec 2011 16:22:39 -0200 Subject: Fix all documentation warnings reported by LDoc. --- src/luarocks/build/make.lua | 3 + src/luarocks/deps.lua | 3 + src/luarocks/fetch.lua | 2 +- src/luarocks/fs/lua.lua | 1 + src/luarocks/fs/unix/tools.lua | 52 ++++++++--------- src/luarocks/fs/win32/tools.lua | 48 ++++++++-------- src/luarocks/manif.lua | 13 +++-- src/luarocks/manif_core.lua | 1 + src/luarocks/path.lua | 124 ++++++++++++++++++++-------------------- src/luarocks/persist.lua | 1 + src/luarocks/search.lua | 4 +- src/luarocks/type_check.lua | 6 ++ src/luarocks/unpack.lua | 2 + src/luarocks/util.lua | 2 +- 14 files changed, 140 insertions(+), 122 deletions(-) (limited to 'src') 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 -- cgit v1.2.3-55-g6feb