lock: source code documentation

Signed-off-by: Gordon Hecker <gh@emlix.com>

diff --git a/generic/lock.lua b/generic/lock.lua
index 428b3062df675b952f30b731f280cae37e87468b..8aff7c9cc71b3ef9a945d4572f43a07b7f3a860e 100644 (file)
--- a/generic/lock.lua
+++ b/generic/lock.lua
@@ -1,10 +1,19 @@
+--- This module maintains lock directories within a lock context.
+-- Remaining lock directories can be removed by calling the cleanup
+-- method.
 module("lock",package.seeall)
 
+--- create a new lock context
+-- @return table: the lock context
 function new()
   local lock = {
 
     locks = {},
 
+    --- create a lock directory
+    -- @param l table: lock object
+    -- @param dir string: lock directory
+    -- @return bool
     lock = function(l, dir)
       local e = new_error("locking failed")
       rc, re = e2lib.mkdir(dir)
@@ -15,6 +24,10 @@ function new()
       return true
     end,
 
+    --- remove a lock directory
+    -- @param l table: lock object
+    -- @param dir string: lock directory
+    -- @return bool
     unlock = function(l, dir)
       local e = new_error("unlocking failed")
       for i,x in ipairs(l.locks) do
@@ -29,6 +42,8 @@ function new()
       return true, nil
     end,
 
+    -- remove all remaining lock directories
+    -- @param l table: lock object
     cleanup = function(l)
       while #l.locks > 0 do
         l:unlock(l.locks[1])