1 files changed, 34 insertions, 1 deletions
diff --git a/lib/supple/track.lua b/lib/supple/track.lua
index b22156f..da8b37f 100644
--- a/lib/supple/track.lua
+++ b/lib/supple/track.lua
@@ -9,6 +9,22 @@
 -- For licence terms, see COPYING
 --
 
+---
+-- Communications tracking for Supple sandboxes.
+--
+-- This module provides a mechanism for keeping track of what goes on in the
+-- communications path of a sandboxed runtime.  The track is held from the
+-- point of view of whichever side caused it to be recorded (typically the
+-- host).  Tracks are best generated by ensuring tracking is enabled and then
+-- calling `supple.host.run`.  Retrieval of the track afterwards is then
+-- simple.
+--
+--     supple.track.start()
+--     supple.host.run(....)
+--     print("Track:\n" .. supple.track.stop())
+--
+
+
 local depth
 local track
 
@@ -34,10 +50,27 @@ local function leave(...)
    end
 end
 
+---
+-- Clear the track data and begin tracking.
+--
+-- Call this routine to clear the current track data and begin tracking comms
+-- and other Supple internals.
+--
+-- @function start
+
 local function start_tracking()
    depth, track = 0, {}
 end
 
+---
+-- Stop tracking and return the current track.
+--
+-- Assuming you have started tracking with `supple.track.start` you can call
+-- this function to stop tracking and retrieve the track as a string.
+--
+-- @treturn string The track data
+-- @function stop
+
 local function stop_tracking()
    if track == nil then
       return "***NO TRACKING DATA***"
@@ -59,4 +92,4 @@ return {
    enter = enter,
    leave = leave,
    record = record,
-}
-\ No newline at end of file
+}