From c543edce571a0600aed313dbf1a13133a58a057d Mon Sep 17 00:00:00 2001
From: Tobias Ulmer <tu@emlix.com>
Date: Tue, 1 Nov 2016 16:17:44 +0100
Subject: [PATCH] update developer documentation

Signed-off-by: Tobias Ulmer <tu@emlix.com>
---
 generic/cache.lua    |  6 ++++++
 generic/e2lib.lua    |  2 ++
 generic/e2option.lua |  4 ++++
 local/chroot.lua     |  3 ++-
 local/e2tool.lua     | 12 ++++++++----
 local/licence.lua    | 10 ++++++----
 local/policy.lua     |  2 +-
 local/sl.lua         | 12 ++++++++----
 local/source.lua     |  3 +++
 9 files changed, 40 insertions(+), 14 deletions(-)

diff --git a/generic/cache.lua b/generic/cache.lua
index ec54a8c..58399da 100644
--- 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 3859167..84696d7 100644
--- 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 32fd10b..a52713f 100644
--- 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 5659f4e..ad378d1 100644
--- 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 4aef52f..127ab22 100644
--- 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 ea8544c..ba67c23 100644
--- 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 5413d99..2e26e89 100644
--- 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 df03826..3330b76 100644
--- 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 4a432d7..87c7351 100644
--- 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 = {}
 
-- 
2.39.5