Add module header comments to make the LDoc index page nicer, and move some of

them around to make LDoc happy, as it doesn't expect local variable
declarations before the actual module is declared.

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")