14 files changed, 32 insertions, 11 deletions

diff --git a/src/luarocks/cfg.lua b/src/luarocks/cfg.lua
index 6007db2f..ec019761 100644
--- a/src/luarocks/cfg.lua
+++ b/src/luarocks/cfg.lua
@@ -1,7 +1,4 @@
 
-local rawset, next, table, pairs, require, io, os, setmetatable, pcall, ipairs, package, type, assert =
-      rawset, next, table, pairs, require, io, os, setmetatable, pcall, ipairs, package, type, assert
-
 --- Configuration for LuaRocks.
 -- Tries to load the user's configuration file and
 -- defines defaults for unset values. See the
@@ -13,6 +10,10 @@ local rawset, next, table, pairs, require, io, os, setmetatable, pcall, ipairs,
 -- (see luarocks.site_config) or their user-specific configuration file
 -- (~/.luarocks/config.lua on Unix or %APPDATA%/luarocks/config.lua on
 -- Windows).
+
+local rawset, next, table, pairs, require, io, os, setmetatable, pcall, ipairs, package, type, assert =
+      rawset, next, table, pairs, require, io, os, setmetatable, pcall, ipairs, package, type, assert
+
 module("luarocks.cfg")
 
 -- Load site-local global configurations
diff --git a/src/luarocks/dir.lua b/src/luarocks/dir.lua
index 00a9317f..69968917 100644
--- a/src/luarocks/dir.lua
+++ b/src/luarocks/dir.lua
@@ -1,4 +1,5 @@
 
+--- Generic utilities for handling pathnames.
 module("luarocks.dir", package.seeall)
 
 separator = "/"
diff --git a/src/luarocks/fs.lua b/src/luarocks/fs.lua
index d2cb3ddb..467b1943 100644
--- a/src/luarocks/fs.lua
+++ b/src/luarocks/fs.lua
@@ -1,11 +1,12 @@
 
-local pairs = pairs
-
 --- Proxy module for filesystem and platform abstractions.
 -- All code using "fs" code should require "luarocks.fs",
 -- and not the various platform-specific implementations.
 -- However, see the documentation of the implementation
 -- for the API reference.
+
+local pairs = pairs
+
 module("luarocks.fs", package.seeall)
 
 local cfg = require("luarocks.cfg")
diff --git a/src/luarocks/fs/unix.lua b/src/luarocks/fs/unix.lua
index 844a6fb0..279eca14 100644
--- a/src/luarocks/fs/unix.lua
+++ b/src/luarocks/fs/unix.lua
@@ -1,8 +1,9 @@
 
+--- Unix implementation of filesystem and platform abstractions.
+
 local assert, type, table, io, package, math, os, ipairs =
       assert, type, table, io, package, math, os, ipairs
 
---- Unix implementation of filesystem and platform abstractions.
 module("luarocks.fs.unix", package.seeall)
 
 local fs = require("luarocks.fs")
diff --git a/src/luarocks/index.lua b/src/luarocks/index.lua
index 01ce266a..6aa7c831 100644
--- a/src/luarocks/index.lua
+++ b/src/luarocks/index.lua
@@ -1,4 +1,5 @@
 
+--- Module which builds the index.html page to be used in rocks servers.
 module("luarocks.index", package.seeall)
 
 local util = require("luarocks.util")
diff --git a/src/luarocks/loader.lua b/src/luarocks/loader.lua
index cab7762e..362a986a 100644
--- a/src/luarocks/loader.lua
+++ b/src/luarocks/loader.lua
@@ -1,4 +1,10 @@
 
+--- A module which installs a Lua package loader that is LuaRocks-aware.
+-- This loader uses dependency information from the LuaRocks tree to load
+-- correct versions of modules. It does this by constructing a "context"
+-- table in the environment, which records which versions of packages were
+-- used to load previous modules, so that the loader chooses versions
+-- that are declared to be compatible with the ones loaded earlier.
 local global_env = _G
 local package, require, ipairs, pairs, table, type, next, unpack =
       package, require, ipairs, pairs, table, type, next, unpack
diff --git a/src/luarocks/manif.lua b/src/luarocks/manif.lua
index 9cacc3ff..f09abf45 100644
--- a/src/luarocks/manif.lua
+++ b/src/luarocks/manif.lua
@@ -1,4 +1,8 @@
 
+--- Module for handling manifest files and tables.
+-- Manifest files describe the contents of a LuaRocks tree or server.
+-- They are loaded into manifest tables, which are then used for
+-- performing searches, matching dependencies, etc.
 module("luarocks.manif", package.seeall)
 
 local manif_core = require("luarocks.manif_core")
diff --git a/src/luarocks/path.lua b/src/luarocks/path.lua
index 99127235..03ed1b90 100644
--- a/src/luarocks/path.lua
+++ b/src/luarocks/path.lua
@@ -1,5 +1,5 @@
 
---- Path and filename handling functions.
+--- LuaRocks-specific path handling functions.
 -- All paths are configured in this module, making it a single
 -- point where the layout of the local installation is defined in LuaRocks.
 module("luarocks.path", package.seeall)
diff --git a/src/luarocks/refresh_cache.lua b/src/luarocks/refresh_cache.lua
index 2ea7e9f4..80730375 100644
--- a/src/luarocks/refresh_cache.lua
+++ b/src/luarocks/refresh_cache.lua
@@ -1,4 +1,5 @@
 
+--- Module implementing the luarocks-admin "refresh_cache" command.
 module("luarocks.refresh_cache", package.seeall)
 
 local util = require("luarocks.util")
diff --git a/src/luarocks/tools/patch.lua b/src/luarocks/tools/patch.lua
index a2b76954..9a89aa48 100644
--- a/src/luarocks/tools/patch.lua
+++ b/src/luarocks/tools/patch.lua
@@ -1,4 +1,4 @@
---- Patch utility to apply unified diffs
+--- Patch utility to apply unified diffs.
 --
 -- http://lua-users.org/wiki/LuaPatch
 --
diff --git a/src/luarocks/tools/tar.lua b/src/luarocks/tools/tar.lua
index e47172fa..ba01a413 100644
--- a/src/luarocks/tools/tar.lua
+++ b/src/luarocks/tools/tar.lua
@@ -1,4 +1,5 @@
 
+--- A pure-Lua implementation of untar (unpacking .tar archives)
 module("luarocks.tools.tar", package.seeall)
 
 local fs = require("luarocks.fs")
diff --git a/src/luarocks/tools/zip.lua b/src/luarocks/tools/zip.lua
index 19f6af85..7534f097 100644
--- a/src/luarocks/tools/zip.lua
+++ b/src/luarocks/tools/zip.lua
@@ -1,4 +1,6 @@
 
+--- A Lua implementation of .zip file archiving (used for creating .rock files),
+-- using only lua-zlib.
 module("luarocks.tools.zip", package.seeall)
 
 local zlib = require("zlib")
diff --git a/src/luarocks/util.lua b/src/luarocks/util.lua
index 4495c024..292ca2ba 100644
--- a/src/luarocks/util.lua
+++ b/src/luarocks/util.lua
@@ -1,10 +1,11 @@
 
-local global_env = _G
-
---- Utility functions shared by other modules.
+--- Assorted utilities for managing tables, plus a scheduler for rollback functions.
 -- Does not requires modules directly (only as locals
 -- inside specific functions) to avoid interdependencies,
 -- as this is used in the bootstrapping stage of luarocks.cfg.
+
+local global_env = _G
+
 module("luarocks.util", package.seeall)
 
 local scheduled_functions = {}
diff --git a/src/luarocks/validate.lua b/src/luarocks/validate.lua
index fbffadc7..03e90ecf 100644
--- a/src/luarocks/validate.lua
+++ b/src/luarocks/validate.lua
@@ -1,4 +1,5 @@
 
+--- Sandboxed test of build/install of all packages in a repository (unfinished and disabled).
 module("luarocks.validate", package.seeall)
 
 local fs = require("luarocks.fs")