From 15922c3632092d08933bc75aeacd772a4621cf89 Mon Sep 17 00:00:00 2001
From: Hisham Muhammad <hisham@gobolinux.org>
Date: Wed, 19 Jun 2013 22:03:40 -0300
Subject: More documentation on deps_modes

---
 src/luarocks/build.lua   |  8 +++++---
 src/luarocks/install.lua |  3 ++-
 src/luarocks/manif.lua   | 12 ++++++++++++
 src/luarocks/path.lua    |  7 +++++++
 4 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/src/luarocks/build.lua b/src/luarocks/build.lua
index 83abbf8d..27afe18d 100644
--- a/src/luarocks/build.lua
+++ b/src/luarocks/build.lua
@@ -111,8 +111,9 @@ end
 -- @param minimal_mode boolean: true if there's no need to fetch,
 -- unpack or change dir (this is used by "luarocks make"). Implies
 -- need_to_fetch = false.
--- @param deps_mode: string: Which trees to check dependencies for:
--- "none", "one", "order" or "all".
+-- @param deps_mode string: Dependency mode: "one" for the current default tree,
+-- "all" for all trees, "order" for all trees with priority >= the current default,
+-- "none" for no trees.
 -- @return boolean or (nil, string, [string]): True if succeeded or 
 -- nil and an error message followed by an error code.
 function build_rockspec(rockspec_file, need_to_fetch, minimal_mode, deps_mode)
@@ -275,7 +276,8 @@ end
 -- @param need_to_fetch boolean: true if sources need to be fetched,
 -- false if the rockspec was obtained from inside a source rock.
 -- @param deps_mode: string: Which trees to check dependencies for:
--- "none", "one", "order" or "all".
+-- "one" for the current default tree, "all" for all trees,
+-- "order" for all trees with priority >= the current default, "none" for no trees.
 -- @return boolean or (nil, string, [string]): True if build was successful,
 -- or false and an error message and an optional error code.
 function build_rock(rock_file, need_to_fetch, deps_mode)
diff --git a/src/luarocks/install.lua b/src/luarocks/install.lua
index c2a54482..3960dcb8 100644
--- a/src/luarocks/install.lua
+++ b/src/luarocks/install.lua
@@ -24,7 +24,8 @@ or a filename of a locally available rock.
 --- Install a binary rock.
 -- @param rock_file string: local or remote filename of a rock.
 -- @param deps_mode: string: Which trees to check dependencies for:
--- "none", "one", "order" or "all". 
+-- "one" for the current default tree, "all" for all trees,
+-- "order" for all trees with priority >= the current default, "none" for no trees.
 -- @return boolean or (nil, string, [string]): True if succeeded or 
 -- nil and an error message and an optional error code.
 function install_binary_rock(rock_file, deps_mode)
diff --git a/src/luarocks/manif.lua b/src/luarocks/manif.lua
index 414c3262..0ce539e9 100644
--- a/src/luarocks/manif.lua
+++ b/src/luarocks/manif.lua
@@ -185,6 +185,9 @@ end
 -- and any dependency inconsistencies or missing dependencies are reported to
 -- standard error.
 -- @param manifest table: a manifest table.
+-- @param deps_mode string: Dependency mode: "one" for the current default tree,
+-- "all" for all trees, "order" for all trees with priority >= the current default,
+-- "none" for no trees.
 local function update_dependencies(manifest, deps_mode)
    assert(type(manifest) == "table")
    assert(type(deps_mode) == "string")
@@ -216,6 +219,9 @@ end
 -- @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.
+-- @param deps_mode string: Dependency mode: "one" for the current default tree,
+-- "all" for all trees, "order" for all trees with priority >= the current default,
+-- "none" for no trees.
 -- @return boolean or (nil, string): true in case of success, or nil followed by an error message.
 local function store_results(results, manifest, deps_mode)
    assert(type(results) == "table")
@@ -253,6 +259,9 @@ end
 -- A file called 'manifest' will be written in the root of the given
 -- repository directory.
 -- @param repo A local repository directory.
+-- @param deps_mode string: Dependency mode: "one" for the current default tree,
+-- "all" for all trees, "order" for all trees with priority >= the current default,
+-- "none" for the default dependency mode from the configuration.
 -- @return boolean or (nil, string): True if manifest was generated,
 -- or nil and an error message.
 function make_manifest(repo, deps_mode)
@@ -286,6 +295,9 @@ end
 -- @param version string: Version of a package from the repository.
 -- @param repo string or nil: Pathname of a local repository. If not given,
 -- the default local repository configured as cfg.rocks_dir is used.
+-- @param deps_mode string: Dependency mode: "one" for the current default tree,
+-- "all" for all trees, "order" for all trees with priority >= the current default,
+-- "none" for using the default dependency mode from the configuration.
 -- @return boolean or (nil, string): True if manifest was generated,
 -- or nil and an error message.
 function update_manifest(name, version, repo, deps_mode)
diff --git a/src/luarocks/path.lua b/src/luarocks/path.lua
index 5e380992..cfe06118 100644
--- a/src/luarocks/path.lua
+++ b/src/luarocks/path.lua
@@ -313,6 +313,13 @@ function use_tree(tree)
    cfg.deploy_lib_dir = deploy_lib_dir(tree)
 end
 
+--- Apply a given function to the active rocks trees based on chosen dependency mode.
+-- @param deps_mode string: Dependency mode: "one" for the current default tree,
+-- "all" for all trees, "order" for all trees with priority >= the current default,
+-- "none" for no trees (this function becomes a nop).
+-- @param fn function: function to be applied, with the tree dir (string) as the first
+-- argument and the remaining varargs of map_trees as the following arguments.
+-- @return a table with all results of invocations of fn collected.
 function map_trees(deps_mode, fn, ...)
    local result = {}
    if deps_mode == "one" then
-- 
cgit v1.2.3-55-g6feb