More documentation

3 files changed, 63 insertions, 2 deletions

diff --git a/config.ld b/config.ld
index 37ac80a..e45aa68 100644
--- a/config.ld
+++ b/config.ld
@@ -1,5 +1,6 @@
 file = {"lib"}
-format = "discount"
+readme = "readme.md"
+format = "lua-markdown"
 project = "Lua Access Control Engine"
 title = "Lace - Lua Access Control Engine"
 dir = "html"
diff --git a/lib/lace.lua b/lib/lace.lua
index 9e039d6..2c76cb8 100644
--- a/lib/lace.lua
+++ b/lib/lace.lua
@@ -9,7 +9,13 @@
 
 --- Lua Access Control Engine.
 --
--- 
+-- The Lua Access Control Engine library consists primarily of a ruleset
+-- compiler and execution engine.  In addition there is a lexer and also a
+-- complex error reporting system designed to ensure application authors who
+-- use Lace in their projects can provide good error messages to their users.
+--
+-- * For compiling rulesets, see `lace.compiler.compile`.
+-- * For running compiled rulesets, see `lace.engine.run`.
 
 local lex = require "lace.lex"
 local compiler = require "lace.compiler"
diff --git a/lib/lace/engine.lua b/lib/lace/engine.lua
index 5484c9b..45c2c33 100644
--- a/lib/lace/engine.lua
+++ b/lib/lace/engine.lua
@@ -7,6 +7,12 @@
 -- For licence terms, see COPYING
 --
 
+--- The runtime engine for the Lua Access Control Engine
+--
+-- Once a ruleset has been compiled, it can be run for multiple inputs without
+-- needing to be recompiled.  This is handy for controlling access to a
+-- long-lived daemon such as an HTTP proxy.
+
 local err = require 'lace.error'
 
 local function _dlace(ctx)
@@ -15,6 +21,16 @@ local function _dlace(ctx)
    return ret
 end
 
+
+--- Set a definition.
+--
+-- @tparam table exec_context The execution context for the runtime.
+-- @tparam string name The name of the define to set.
+-- @tparam table defn The definition function to use.
+-- @treturn boolean Returns true if the definition was set successfully.
+-- @treturn nil|table If the definition was not set successfully then this is
+--                    the error table ready to have context added to it.
+-- @function define
 local function set_define(exec_context, name, defn)
    local dlace = _dlace(exec_context)
    dlace.defs = dlace.defs or {}
@@ -25,6 +41,17 @@ local function set_define(exec_context, name, defn)
    return true
 end
 
+--- Test a definition.
+--
+-- @tparam table exec_context The execution context for the runtime.
+-- @tparam string name The name of the define to test.
+-- @treturn boolean|nil If the named definition does not exist, this is nil.
+--                      Otherwise it is true iff. the definition's function
+--                      results in true.
+-- @treturn nil|table If the named definition does not exist, this is the error
+--                    table ready for filling out with more context.
+--                    Otherwise it is nil.
+-- @function test
 local function test_define(exec_context, name)
    local dlace = _dlace(exec_context)
    dlace.defs = dlace.defs or {}
@@ -36,6 +63,22 @@ local function test_define(exec_context, name)
    return defn.fn(exec_context, unpack(defn.args))
 end
 
+--- Internal routine for running sub-rulesets
+--
+-- @tparam table ruleset The compiled ruleset to run.
+-- @tparam table exec_context The execution context for the runtime.
+-- @treturn nil|boolean|string The first return value is `nil` in the case
+--                             of a runtime error, `false` if a Lace error
+--                             was encountered during runtime, otherwise it it
+--                             a result string (typically `allow` or `deny`).
+--                             In addition, internally, an empty result string
+--                             will be returned if no result was set by the
+--                             sub-ruleset.
+-- @treturn nil|string If an error was encountered, this is the error message,
+--                     otherwise it is an additional message to go with the
+--                     result if there was one, or `nil` in the case of no
+--                     result value being set by the ruleset.
+-- @function internal_run
 local function internal_run_ruleset(ruleset, exec_context)
    -- We iterate the ruleset, returning the first time
    -- a rule either errors, or returns a stopping result
@@ -58,6 +101,17 @@ local function internal_run_ruleset(ruleset, exec_context)
    return ""
 end
 
+--- Run a ruleset.
+--
+-- @tparam table ruleset The compiled ruleset to run.
+-- @tparam table exec_context The execution context for the runtime.
+-- @treturn nil|boolean|string The first return value is `nil` in the case
+--                             of a runtime error, `false` if a Lace error
+--                             was encountered during runtime, otherwise it it
+--                             a result string (typically `allow` or `deny`).
+-- @treturn string If an error was encountered, this is the error message,
+--                 otherwise it is an additional message to go with the result.
+-- @function run
 local function run_ruleset(ruleset, exec_context)
    local ok, ret, msg = xpcall(function() 
 				  return internal_run_ruleset(ruleset, exec_context)