update developer documentation

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

diff --git a/generic/cache.lua b/generic/cache.lua
index ec54a8cd753901e56e7922155d018841313d100b..58399dafac2d5efd06838cc3d315020d185c30c5 100644 (file)
--- a/generic/cache.lua
+++ b/generic/cache.lua
@@ -394,6 +394,12 @@ local function file_in_cache(c, server, location, flags)
     return true, nil, cf
 end
 
+--- Check whether islocal is enabled or not.
+-- @param c cache table.
+-- @param server server name.
+-- @param flags cache flags.
+-- @return True if local, false if not.
+-- @return Error object on error.
 function cache.islocal_enabled(c, server, flags)
     assertIsTable(c)
     assertIsStringN(server)

diff --git a/generic/e2lib.lua b/generic/e2lib.lua
index 385916710066c1d6208d6954494a35e1a9cb2206..84696d76941eec054577ac27926163cfb5e731aa 100644 (file)
--- a/generic/e2lib.lua
+++ b/generic/e2lib.lua
@@ -51,6 +51,8 @@ local plugin = require("plugin")
 local tools = require("tools")
 local trace = require("trace")
 
+--- Various global settings
+-- @table globals
 e2lib.globals = strict.lock({
     logflags = {
         { "v1", true },    -- minimal

diff --git a/generic/e2option.lua b/generic/e2option.lua
index 32fd10b31a93dde9ee632c333e67be5b8d074fd8..a52713fe3920cace98e59f52005210bbf7c3cdf7 100644 (file)
--- a/generic/e2option.lua
+++ b/generic/e2option.lua
@@ -33,6 +33,8 @@ local options = {}
 local aliases = {}
 local optionlist = {} -- ordered list of option names
 
+--- e2option.parse() result is stored in this table for later reference.
+-- @table opts
 e2option.opts = {}
 
 --- register a flag option
@@ -88,6 +90,7 @@ function e2option.alias(alias, option)
     aliases[alias] = option
 end
 
+--- Sets up default options for all commands.
 local function defaultoptions()
     local category = "Verbosity Control Options"
     e2option.option("e2-config", "specify configuration file", nil,
@@ -216,6 +219,7 @@ local function defaultoptions()
     category)
 end
 
+--- Load user default options if set in $HOME/.e2/e2rc
 local function userdefaultoptions(opts)
     local home = e2lib.globals.osenv["HOME"]
     if not home then

diff --git a/local/chroot.lua b/local/chroot.lua
index 5659f4ea2a45413714fc2d097820ca10b6e83b22..ad378d1a133b884ea977dab1f81aa15f4729827d 100644 (file)
--- a/local/chroot.lua
+++ b/local/chroot.lua
@@ -58,7 +58,7 @@ chroot.groups_byname = {}
 chroot.groups_sorted = {}
 
 --- Chroot class.
--- @see generic.class
+-- @type chroot
 chroot.chroot = class("chroot")
 
 --- Chroot group object constructor.
@@ -162,6 +162,7 @@ function chroot.chroot:chrootgroupid(info)
     self._chrootgroupid = hash.hash_finish(hc)
     return self._chrootgroupid
 end
+--- @section end
 
 --- Load and validate chroot configuration. Populates chroot.groups_byname,
 -- chroot.groups_sorted and chroot.groups_default.

diff --git a/local/e2tool.lua b/local/e2tool.lua
index 4aef52f1945179e3fc1e90e5c5f30d08b42bceb5..127ab22cfc3a87e74a9109fa5699e58256b1c754 100644 (file)
--- a/local/e2tool.lua
+++ b/local/e2tool.lua
@@ -95,12 +95,12 @@ function e2tool.set_umask()
     e2lib.umask(_chroot_umask)
 end
 
--- set umask back to the value used on the host
+--- set umask back to the value used on the host
 function e2tool.reset_umask()
     e2lib.umask(_host_umask)
 end
 
--- initialize the umask set/reset mechanism (i.e. store the host umask)
+--- initialize the umask set/reset mechanism (i.e. store the host umask)
 local function init_umask()
     -- save the umask value we run with
     _host_umask = e2lib.umask(_chroot_umask)
@@ -827,7 +827,7 @@ function e2tool.buildid(info, resultname)
     return result.results[resultname]:buildid()
 end
 
---- select results based upon a list of results usually given on the
+--- select (mark) results based upon a list of results usually given on the
 -- command line. Parameters are assigned to all selected results.
 -- @param info the info structure
 -- @param results table: list of result names
@@ -875,6 +875,10 @@ function e2tool.select_results(info, results, force_rebuild, keep_chroot, build_
     return true
 end
 
+--- Build all results in resultv in-order.
+-- @param resultv Result name vector.
+-- @return True on success, false on error.
+-- @return Error object on failure.
 function e2tool.build_results(resultv)
     e2lib.logf(3, "building results")
 
@@ -900,7 +904,7 @@ function e2tool.build_results(resultv)
     return true
 end
 
---- print selection status for a list of results
+--- Print selection status for a list of results
 -- @param info
 -- @param resultvec table: list of result names
 -- @return bool

diff --git a/local/licence.lua b/local/licence.lua
index ea8544ccda26e0d0e3331617e21e4cc72ee7e4e7..ba67c239d5556ad1266bd7a23605c631914e6364 100644 (file)
--- a/local/licence.lua
+++ b/local/licence.lua
@@ -30,15 +30,16 @@ local hash = require("hash")
 local projenv = require("projenv")
 local strict = require("strict")
 
---- Licence base class.
--- @see generic.class
-licence.licence = class("licence")
-
 --- Dictionary of loaded licence objects, indexed by name.
 licence.licences = {}
+
 --- Vector of loaded licence objects, sorted by name.
 licence.licences_sorted = {}
 
+--- Licence base class.
+-- @type licence
+licence.licence = class("licence")
+
 --- Create a new licence object.
 -- @param name Licence name string.
 -- @return May throw error(err) on invalid input.
@@ -149,6 +150,7 @@ function licence.licence:licenceid(info)
 
     return self._licenceid
 end
+--- @section end
 
 --- Load project licence config, validate, and populate the licences,
 -- licences_sorted tables with licence objects.

diff --git a/local/policy.lua b/local/policy.lua
index 5413d9945cd32f5435acdd40f53b6ffe7870e2b0..2e26e89a180a951af2cd5bcab60bd5130fbf97f5 100644 (file)
--- a/local/policy.lua
+++ b/local/policy.lua
@@ -103,7 +103,7 @@ local buildid_scratch_cache = {}
 -- @param buildid the buildid
 -- @return the buildid
 local function buildid_scratch(buildid)
-    --- XXX: Always returning a fixed buildid string does not work when
+    -- XXX: Always returning a fixed buildid string does not work when
     -- the scratch results gets used by results not in scratch mode.
     -- eg. if we have a result graph like this: root->tag->wc-mode->tag
     -- the final tag would only be built once and then cached globally.

diff --git a/local/sl.lua b/local/sl.lua
index df038263c665549d4bc68ed50fe7ef7e46f4cf3b..3330b7670603ba2a2d11567edfdd7129315663c6 100644 (file)
--- a/local/sl.lua
+++ b/local/sl.lua
@@ -24,9 +24,11 @@ local err = require("err")
 local e2lib = require("e2lib")
 local strict = require("strict")
 
---- String list class that keeps entries in sorted order
--- while ignoring duplicate entries.
--- Trying to use string list with anything but strings throws an exception.
+--- String list.
+-- String list class that keeps entries in sorted order while ignoring
+-- duplicate entries. Trying to use string list with anything but strings throws
+-- an exception.
+-- @type sl
 sl.sl = class("sl")
 
 --- Initialize string list [sl:new()]
@@ -75,7 +77,7 @@ function sl.sl:insert_sl(entrysl)
     end
 end
 
---- Remove *all* matching entries from the string list.
+--- Remove matching entry from string list.
 -- @param entry The entry.
 -- @return True when one or more entries were removed, false otherwise.
 function sl.sl:remove(entry)
@@ -183,6 +185,8 @@ function sl.sl:unpack()
     return unpack(self:totable())
 end
 
+--- @section end
+
 return strict.lock(sl)
 
 -- vim:sw=4:sts=4:et:

diff --git a/local/source.lua b/local/source.lua
index 4a432d7465f13ea0d15eb3ae3a4c775b2e4f7117..87c7351e573f6b011e3c3a46aa256b0e98ead46f 100644 (file)
--- a/local/source.lua
+++ b/local/source.lua
@@ -34,6 +34,7 @@ local strict = require("strict")
 local source_types = {}
 
 --- Source base class.
+-- @type basic_source
 source.basic_source = class("basic_source")
 
 --- Source base constructor. Assert error on invalid input.
@@ -120,6 +121,8 @@ function source.basic_source:display()
         self._type, self._name))
 end
 
+--- @section end
+
 --- Dictionary holding all source objects indexed by their name.
 source.sources = {}