From: Tobias Ulmer <tu@emlix.com>
Date: Wed, 12 Dec 2012 01:12:35 +0000 (+0100)
Subject: Add module descriptions and fix small ldoc errors
X-Git-Tag: e2factory-2.3.13rc1~72
X-Git-Url: https://git.e2factory.org/?a=commitdiff_plain;h=e1a94a3833c0d99d2c6fe3732ac7803e66328a8e;p=e2factory.git

Add module descriptions and fix small ldoc errors

Signed-off-by: Tobias Ulmer <tu@emlix.com>
---

diff --git a/generic/cache.lua b/generic/cache.lua
index 4260347..da1cc6d 100644
--- a/generic/cache.lua
+++ b/generic/cache.lua
@@ -1,3 +1,6 @@
+--- Cache
+-- @module generic.cache
+
 --[[
    e2factory, the emlix embedded build system
 
@@ -381,6 +384,7 @@ end
 -- @param c the cache data structure
 -- @param server the server to fetch the file from
 -- @param location the location on the server
+-- @param flags
 -- @return bool
 -- @return an error object on failure
 function cache.writeback(c, server, location, flags)
@@ -412,6 +416,7 @@ end
 -- @param c the cache data structure
 -- @param server the server to fetch the file from
 -- @param location the location on the server
+-- @param flags
 -- @return bool
 -- @return an error object on failure
 function cache.cache_file(c, server, location, flags)
@@ -452,6 +457,7 @@ end
 -- @param c the cache data structure
 -- @param server the server where the file is located
 -- @param location the location on the server
+-- @param flags unused parameter
 -- @return string the path to the cached file, nil on error
 -- @return an error object on failure
 function cache.file_path(c, server, location, flags)
diff --git a/generic/e2lib.lua b/generic/e2lib.lua
index 1db0ec3..4d80617 100644
--- a/generic/e2lib.lua
+++ b/generic/e2lib.lua
@@ -1,3 +1,6 @@
+--- Utility and Helper Library
+-- @module generic.e2lib
+
 --[[
    e2factory, the emlix embedded build system
 
@@ -526,8 +529,6 @@ end
 -- is true
 -- @param level number: loglevel
 -- @param msg string: log message
--- @param ... strings: arguments required for the format string
--- @return nil
 function e2lib.log(level, msg)
     if level < 1 or level > 4 then
         bomb("invalid log level")
@@ -560,7 +561,6 @@ function e2lib.log(level, msg)
         end
         io.stderr:write(msg .. "\n")
     end
-    return nil
 end
 
 function e2lib.rotate_log(file)
@@ -709,7 +709,7 @@ function e2lib.tartype(path)
 end
 
 --- translate filename suffixes to valid tartypes for e2-su-2.2
--- @filename string: filename
+-- @param filename string: filename
 -- @return string: tartype, or nil on failure
 -- @return an error object on failure
 function e2lib.tartype_by_suffix(filename)
@@ -898,7 +898,6 @@ end
 
 --- read the local extension configuration
 -- This function must run while being located in the projects root directory
--- @param root string: path to project
 -- @return the extension configuration table
 -- @return an error object on failure
 function e2lib.read_extension_config()
@@ -1430,7 +1429,7 @@ end
 --- call the touch tool with flags and filename
 -- @param file string: the file parameter
 -- @param flags string: flags to pass to touch (optional)
--- @returns bool
+-- @return bool
 function e2lib.touch(file, flags)
     if not flags then
         flags = ""
@@ -1569,7 +1568,7 @@ function e2lib.svn(argv)
 end
 
 --- call the ln command
--- @param destination string: destination name
+-- @param dst string: destination name
 -- @param link string: link name
 -- @return bool
 -- @return the last line of captured output
@@ -1875,7 +1874,7 @@ end
 
 --- parse a server:location string, taking a default server into account
 -- @param arg string: the string to parse
--- @param dafault server string: the default server name
+-- @param default_server string: the default server name
 -- @return a table with fields server and location, nil on error
 -- @return nil, an error string on error
 function e2lib.parse_server_location(arg, default_server)
diff --git a/generic/e2option.lua b/generic/e2option.lua
index 6a05468..32cc853 100644
--- a/generic/e2option.lua
+++ b/generic/e2option.lua
@@ -1,3 +1,6 @@
+--- Option Parser
+-- @module generic.e2option
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/generic/err.lua b/generic/err.lua
index 4fdc0f9..4bb0b2d 100644
--- a/generic/err.lua
+++ b/generic/err.lua
@@ -1,3 +1,6 @@
+--- Error Object
+-- @module generic.err
+
 --[[
    e2factory, the emlix embedded build system
 
@@ -86,6 +89,7 @@ end
 
 --- get the error counter
 -- @param e the error object
+-- @param n unused
 -- @return number: the error counter
 function err.getcount(e, n)
     return e.count
diff --git a/generic/generic_git.lua b/generic/generic_git.lua
index 88a1502..b916d66 100644
--- a/generic/generic_git.lua
+++ b/generic/generic_git.lua
@@ -1,3 +1,6 @@
+--- Git
+-- @module generic.generic_git
+
 --[[
    e2factory, the emlix embedded build system
 
@@ -39,6 +42,7 @@ local strict = require("strict")
 --- clone a git repository
 -- @param surl url to the server
 -- @param location location relative to the server url
+-- @param destdir
 -- @param skip_checkout bool: pass -n to git clone?
 -- @return true on success, false on error
 -- @return nil, an error object on failure
@@ -289,7 +293,7 @@ function generic_git.git_url1(u)
 end
 
 --- clone a git repository by server and location
--- @param cache
+-- @param c
 -- @param server
 -- @param location
 -- @param destdir string: destination directory
@@ -526,8 +530,8 @@ function generic_git.verify_clean_repository(gitwc)
 end
 
 --- verify that HEAD matches the given tag
--- @param gitdir string: gitdir (optional, default: .git)
--- @param tag string: tag name
+-- @param gitwc string: gitdir (optional, default: .git)
+-- @param verify_tag string: tag name
 -- @return bool, or nil on error
 -- @return an error object on failure
 function generic_git.verify_head_match_tag(gitwc, verify_tag)
@@ -579,7 +583,7 @@ end
 -- @param llocation string: working copy location on local server
 -- @param rserver string: remote server
 -- @param rlocation string: repository location on remote server
--- @param flags: table of flags
+-- @param flags table of flags
 -- @return bool
 -- @return nil, or an error string on error
 function generic_git.new_repository(c, lserver, llocation, rserver, rlocation, flags)
diff --git a/generic/hash.lua b/generic/hash.lua
index 30f2908..530b2fb 100644
--- a/generic/hash.lua
+++ b/generic/hash.lua
@@ -1,3 +1,6 @@
+--- Hash
+-- @module generic.hash
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/generic/lock.lua b/generic/lock.lua
index c1f299b..290b748 100644
--- a/generic/lock.lua
+++ b/generic/lock.lua
@@ -1,3 +1,11 @@
+--- Locking module.
+--
+-- This module maintains lock directories within a lock context.
+-- Remaining lock directories can be removed by calling the cleanup
+-- method.
+--
+-- @module generic.lock
+
 --[[
    e2factory, the emlix embedded build system
 
@@ -26,9 +34,6 @@
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 ]]
 
---- This module maintains lock directories within a lock context.
--- Remaining lock directories can be removed by calling the cleanup
--- method.
 local lock = {}
 local err = require("err")
 local e2lib = require("e2lib")
diff --git a/generic/luafile.lua b/generic/luafile.lua
index 592cdd3..b79c678 100644
--- a/generic/luafile.lua
+++ b/generic/luafile.lua
@@ -1,3 +1,6 @@
+--- File handling.
+-- @module generic.luafile
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/generic/plugin.lua b/generic/plugin.lua
index 396dcd7..7fac4d5 100644
--- a/generic/plugin.lua
+++ b/generic/plugin.lua
@@ -1,3 +1,6 @@
+--- Plugin Loader.
+-- @module generic.plugin
+
 --[[
    e2factory, the emlix embedded build system
 
@@ -76,7 +79,7 @@ local plugins = {}
 
 --- load a plugin
 -- @param dir string: plugin directory
--- @param plugin_file string: filename
+-- @param p string: plugin filename
 -- @param ctx table: plugin context
 -- @return bool
 -- @return an error object on failure
diff --git a/generic/strict.lua b/generic/strict.lua
index 2d8be78..60bc5b5 100644
--- a/generic/strict.lua
+++ b/generic/strict.lua
@@ -1,3 +1,6 @@
+--- Strict table handling.
+-- @module generic.strict
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/generic/tools.lua b/generic/tools.lua
index 25a7b23..5102f4a 100644
--- a/generic/tools.lua
+++ b/generic/tools.lua
@@ -1,3 +1,6 @@
+--- External Tools Support.
+-- @module generic.tools
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/generic/transport.lua b/generic/transport.lua
index bd238d6..baad417 100644
--- a/generic/transport.lua
+++ b/generic/transport.lua
@@ -1,3 +1,6 @@
+--- Transport Backend
+-- @module generic.transport
+
 --[[
    e2factory, the emlix embedded build system
 
@@ -83,7 +86,7 @@ end
 -- @param opts table: options vector to pass to rsync
 -- @param user string: optional username or nil
 -- @param server string: the server part of the directory to create
--- @param directory string: the directory to create on the server
+-- @param dir string: the directory to create on the server
 -- @return bool
 -- @return an error object on failure
 local function rsync_ssh_mkdir(opts, user, server, dir)
diff --git a/generic/url.lua b/generic/url.lua
index 5d65240..743dfcb 100644
--- a/generic/url.lua
+++ b/generic/url.lua
@@ -1,3 +1,6 @@
+--- URL Parser.
+-- @module generic.url
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/global/e2-create-project.lua b/global/e2-create-project.lua
index 5d78118..8f9e7c0 100644
--- a/global/e2-create-project.lua
+++ b/global/e2-create-project.lua
@@ -1,3 +1,6 @@
+--- e2-create-project command
+-- @module global.e2-create-project
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/global/e2-fetch-project.lua b/global/e2-fetch-project.lua
index 7d502cb..0fbf2a7 100644
--- a/global/e2-fetch-project.lua
+++ b/global/e2-fetch-project.lua
@@ -1,3 +1,6 @@
+--- e2-fetch-project command
+-- @module global.e2-fetch-project
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/global/e2-install-e2.lua b/global/e2-install-e2.lua
index 0720c06..f9d041a 100644
--- a/global/e2-install-e2.lua
+++ b/global/e2-install-e2.lua
@@ -1,3 +1,6 @@
+--- e2-install-e2 command
+-- @module global.e2-install-e2
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/global/e2.lua b/global/e2.lua
index 549b01f..9cd57e0 100644
--- a/global/e2.lua
+++ b/global/e2.lua
@@ -1,3 +1,6 @@
+--- e2 command
+-- @module global.e2
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/local/cvs.lua b/local/cvs.lua
index bb1cbb4..7d1fe61 100644
--- a/local/cvs.lua
+++ b/local/cvs.lua
@@ -1,3 +1,6 @@
+--- CVS Plugin
+-- @module local.cvs
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/local/e2-build.lua b/local/e2-build.lua
index 840a621..29c8c67 100644
--- a/local/e2-build.lua
+++ b/local/e2-build.lua
@@ -1,3 +1,6 @@
+--- e2-build command
+-- @module local.e2-build
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/local/e2-cf.lua b/local/e2-cf.lua
index 58f68ee..f3da646 100644
--- a/local/e2-cf.lua
+++ b/local/e2-cf.lua
@@ -1,3 +1,6 @@
+--- e2-cf command
+-- @module local.e2-cf
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/local/e2-dlist.lua b/local/e2-dlist.lua
index c5da5f1..8e2f25a 100644
--- a/local/e2-dlist.lua
+++ b/local/e2-dlist.lua
@@ -1,3 +1,6 @@
+--- e2-dlist command
+-- @module local.e2-dlist
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/local/e2-dsort.lua b/local/e2-dsort.lua
index 9de6838..7dfffc3 100644
--- a/local/e2-dsort.lua
+++ b/local/e2-dsort.lua
@@ -1,3 +1,6 @@
+--- e2-dlist command
+-- @module local.e2-dlist
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/local/e2-fetch-sources.lua b/local/e2-fetch-sources.lua
index 962d5ee..8e9f286 100644
--- a/local/e2-fetch-sources.lua
+++ b/local/e2-fetch-sources.lua
@@ -1,3 +1,6 @@
+--- e2-fetch-source command
+-- @module local.e2-fetch-source
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/local/e2-ls-project.lua b/local/e2-ls-project.lua
index 69a099e..10cb4af 100644
--- a/local/e2-ls-project.lua
+++ b/local/e2-ls-project.lua
@@ -1,3 +1,6 @@
+--- e2-ls-project command
+-- @module local.e2-ls-project
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/local/e2-new-source.lua b/local/e2-new-source.lua
index 89579c9..b0f63d4 100644
--- a/local/e2-new-source.lua
+++ b/local/e2-new-source.lua
@@ -1,3 +1,6 @@
+--- e2-new-source command
+-- @module local.e2-new-source
+
 --[[
    e2factory, the emlix embedded build system
 
@@ -117,7 +120,7 @@ end
 
 --- generate a sha1 checksum file
 -- @param source_file string: source file name
--- @param checksum_file: checksum file name
+-- @param checksum_file checksum file name
 -- @return bool
 -- @return nil, an error string on error
 local function write_checksum_file_sha1(source_file, checksum_file)
diff --git a/local/e2-playground.lua b/local/e2-playground.lua
index 1ed062e..0635677 100644
--- a/local/e2-playground.lua
+++ b/local/e2-playground.lua
@@ -1,3 +1,6 @@
+--- e2-playground command
+-- @module local.e2-playground
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/local/e2build.lua b/local/e2build.lua
index 2f03b01..b98be4d 100644
--- a/local/e2build.lua
+++ b/local/e2build.lua
@@ -1,3 +1,6 @@
+--- Core build logic
+-- @module local.e2build
+
 --[[
    e2factory, the emlix embedded build system
 
@@ -935,6 +938,7 @@ end
 --- build a result
 -- @param info
 -- @param result string: result name
+-- @param return_flags
 -- @return bool
 -- @return an error object on failure
 local function build_result(info, result, return_flags)
@@ -1013,7 +1017,9 @@ end
 -- sources being the result collecting the project:
 -- the results sources and iso won't be included, as that would lead to
 -- an impossibility to calculate buildids (infinite recursion)
--- @param c table: build context
+-- @param info info table
+-- @param r
+-- @param return_flags
 -- @return bool
 -- @return an error object on failure
 local function collect_project(info, r, return_flags)
diff --git a/local/e2tool.lua b/local/e2tool.lua
index 10a3ac0..e34ad00 100644
--- a/local/e2tool.lua
+++ b/local/e2tool.lua
@@ -1,3 +1,6 @@
+--- Core data structure manipulation
+-- @module local.e2tool
+
 --[[
    e2factory, the emlix embedded build system
 
@@ -296,8 +299,9 @@ end
 -- @field filename string: config file name
 
 --- load config file and return a list of config item tables
+-- @param info info table
 -- @param path string: file to load
--- @param type list of strings: allowed config types
+-- @param types list of strings: allowed config types
 -- @return list of config items
 -- @return an error object on failure
 local function load_user_config2(info, path, types)
@@ -1965,6 +1969,7 @@ end
 
 --- calculate a representation for file content. The name and location
 -- attributes are not included.
+-- @param info info table
 -- @param file table: file table from configuration
 -- @return fileid string: hash value, or nil
 -- @return an error object on failure
@@ -2030,7 +2035,6 @@ end
 -- XXX this function always succeeds or aborts
 -- @param info
 -- @param resultname
--- @param mode
 -- @return the buildid
 function e2tool.buildid(info, resultname)
     e2lib.log(4, string.format("get buildid for %s", resultname))
@@ -2330,7 +2334,7 @@ local function check_workingcopies(info)
 end
 
 --- parse build numbers from a string and store to the build number table
--- @param info: the info table
+-- @param info the info table
 -- @param s string: the string to parse
 -- @param build_numbers table: build number table (optional)
 -- @return bool
@@ -2366,7 +2370,7 @@ end
 
 --- serialize the build number table suitable for storage or network
 -- transport
--- @param info: the info table
+-- @param info info table
 -- @param build_numbers table: build number table (optional)
 -- @return s string: serialized build numbers, or nil
 -- @return nil, an error object on error
diff --git a/local/environment.lua b/local/environment.lua
index b234d1c..f62d7a2 100644
--- a/local/environment.lua
+++ b/local/environment.lua
@@ -1,3 +1,6 @@
+--- Environment Manipulation
+-- @module local.environment
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/local/files.lua b/local/files.lua
index f5a979a..f0182a5 100644
--- a/local/files.lua
+++ b/local/files.lua
@@ -1,3 +1,6 @@
+--- Files Plugin
+-- @module local.files
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/local/git.lua b/local/git.lua
index cb658d9..ac04fa9 100644
--- a/local/git.lua
+++ b/local/git.lua
@@ -1,3 +1,6 @@
+--- Git Plugin
+-- @module local.git
+
 --[[
    e2factory, the emlix embedded build system
 
@@ -275,6 +278,8 @@ end
 --- prepare a git source
 -- @param info the info structure
 -- @param sourcename string
+-- @param sourceset
+-- @param buildpath
 -- @return bool
 -- @return nil on success, an error string on error
 function git.prepare_source(info, sourcename, sourceset, buildpath)
@@ -442,6 +447,7 @@ end
 --- calculate an id for a source
 -- @param info
 -- @param sourcename
+-- @param sourceset
 -- @return string: the sourceid, or nil
 -- @return an error string
 function git.sourceid(info, sourcename, sourceset)
diff --git a/local/policy.lua b/local/policy.lua
index f9b3d25..a1966e4 100644
--- a/local/policy.lua
+++ b/local/policy.lua
@@ -1,3 +1,6 @@
+--- Policy
+-- @module local.policy
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/local/scm.lua b/local/scm.lua
index caba4cf..b5ba458 100644
--- a/local/scm.lua
+++ b/local/scm.lua
@@ -1,3 +1,6 @@
+--- SCM Interface
+-- @module local.scm
+
 --[[
    e2factory, the emlix embedded build system
 
diff --git a/local/svn.lua b/local/svn.lua
index 44cb1b6..d207108 100644
--- a/local/svn.lua
+++ b/local/svn.lua
@@ -1,3 +1,6 @@
+--- Subversion Plugin
+-- @module local.svn
+
 --[[
    e2factory, the emlix embedded build system
 
@@ -212,6 +215,7 @@ end
 --- calculate an id for a source
 -- @param info
 -- @param sourcename
+-- @param source_set
 function svn.sourceid(info, sourcename, source_set)
     local src = info.sources[sourcename]
     local rc, e