Add user documentation. Skipping internal docs for now

1 files changed, 19 insertions, 0 deletions

diff --git a/lib/supple/sandbox.lua b/lib/supple/sandbox.lua
index f4025bc..a6d9513 100644
--- a/lib/supple/sandbox.lua
+++ b/lib/supple/sandbox.lua
@@ -19,6 +19,17 @@
 -- For licence terms, see COPYING
 --
 
+--- Running code in sandboxes
+--
+-- This module is used by the sandbox code itself to start running sandboxed
+-- Lua.  The only entry point is invoked by the sandbox C wrapper during
+-- startup.  From here the sandbox locks itself down and then begins to listen
+-- for work to do.
+--
+-- You should only need to interact with this module if you are writing your
+-- own Supple wrapper binary to use instead of the provided wrapper.
+--
+
 local capi = require 'supple.capi'
 local objects = require 'supple.objects'
 local comms = require 'supple.comms'
@@ -91,6 +102,14 @@ local function wrapped_unpack(t)
    return unpack(packed)
 end
 
+--- Start the sandbox running
+--
+-- This routine is invoked by the sandbox wrapper C code and starts the sandbox
+-- running.  Approximately it locks the sandbox down, including various limits
+-- such as chroot, rlimits, dropping privileges, and seccomp mode if available.
+-- Then it begins the main RPC loop for the sandbox.
+--
+-- @function run
 local function run()
    -- Run the sandbox
    local result, errno = capi.lockdown()