GSoC: Documentation #1

2 files changed, 63 insertions, 3 deletions

diff --git a/libs/lucid/luasrc/lucid.lua b/libs/lucid/luasrc/lucid.lua
index 34452a599..b10365579 100644
--- a/libs/lucid/luasrc/lucid.lua
+++ b/libs/lucid/luasrc/lucid.lua
@@ -41,7 +41,7 @@ local UCINAME = UCINAME
 local SSTATE = "/tmp/.lucid_store"
 
 
-
+--- Starts a new LuCId superprocess.
 function start()
 	prepare()
 
@@ -60,6 +60,7 @@ function start()
 	run()
 end
 
+--- Stops any running LuCId superprocess. 
 function stop()
 	local pid = tonumber(state:get(UCINAME, "main", "pid"))
 	if pid then
@@ -68,6 +69,7 @@ function stop()
 	return false
 end
 
+--- Prepares the slaves, daemons and publishers, allocate resources.
 function prepare()
 	local debug = tonumber((cursor:get(UCINAME, "main", "debug")))
 	
@@ -104,6 +106,8 @@ function prepare()
 	end)
 end
 	
+--- Run the superprocess if prepared before. 
+-- This main function of LuCId will wait for events on given file descriptors.
 function run()
 	local pollint = tonumber((cursor:get(UCINAME, "main", "pollinterval")))
 
@@ -136,11 +140,20 @@ function run()
 	end
 end
 
+--- Add a file descriptor for the main loop and associate handler functions.
+-- @param polle Table containing: {fd = FILE DESCRIPTOR, events = POLL EVENTS,
+-- handler = EVENT HANDLER CALLBACK}
+-- @see unregister_pollfd
+-- @return boolean status
 function register_pollfd(polle)
 	pollt[#pollt+1] = polle
 	return true 
 end
 
+--- Unregister a file desciptor and associate handler from the main loop.
+-- @param polle Poll descriptor
+-- @see register_pollfd
+-- @return boolean status
 function unregister_pollfd(polle)
 	for k, v in ipairs(pollt) do
 		if v == polle then
@@ -151,6 +164,8 @@ function unregister_pollfd(polle)
 	return false
 end
 
+--- Close all registered file descriptors from main loop.
+-- This is useful for forked child processes. 
 function close_pollfds()
 	for k, v in ipairs(pollt) do
 		if v.fd and v.fd.close then
@@ -159,11 +174,19 @@ function close_pollfds()
 	end
 end
 
+--- Register a tick function that will be called at each cycle of the main loop.
+-- @param cb Callback
+-- @see unregister_tick
+-- @return boolean status
 function register_tick(cb)
 	tickt[#tickt+1] = cb
 	return true
 end
 
+--- Unregister a tick function from the main loop.
+-- @param cb Callback
+-- @see register_tick
+-- @return boolean status
 function unregister_tick(cb)
 	for k, v in ipairs(tickt) do
 		if v == cb then
@@ -174,10 +197,14 @@ function unregister_tick(cb)
 	return false
 end
 
+--- Create a new child process from a Lua function and assign a destructor.
+-- @param threadcb main function of the new process
+-- @param waitcb destructor callback
+-- @return process identifier or nil, error code, error message
 function create_process(threadcb, waitcb)
 	local threadlimit = tonumber(cursor:get(UCINAME, "main", "threadlimit"))
 	if threadlimit and tcount >= threadlimit then
-		nixio.syslog("warning", "Unable to create thread: process limit reached")
+		nixio.syslog("warning", "Cannot create thread: process limit reached")
 		return nil
 	end
 	local pid, code, err = nixio.fork()
@@ -193,6 +220,9 @@ function create_process(threadcb, waitcb)
 	return pid, code, err
 end
 
+--- Prepare a daemon from a given configuration table.
+-- @param config Configuration data.
+-- @return boolean status or nil, error code, error message
 function prepare_daemon(config)
 	nixio.syslog("info", "Preparing daemon " .. config[".name"])
 	local modname = cursor:get(UCINAME, config.slave)
@@ -210,6 +240,9 @@ function prepare_daemon(config)
 	return module.prepare_daemon(config, _M)
 end
 
+--- Prepare a slave.
+-- @param name slave name
+-- @return table containing slave module and configuration or nil, error message
 function prepare_slave(name)
 	local slave = slaves[name]
 	if not slave then
@@ -228,16 +261,24 @@ function prepare_slave(name)
 	end
 end
 
+--- Return a list of available network interfaces on the host.
+-- @return table returned by nixio.getifaddrs()
 function get_interfaces()
 	return ifaddrs
 end
 
+--- Revoke process privileges.
+-- @param user new user name or uid
+-- @param group new group name or gid
+-- @return boolean status or nil, error code, error message
 function revoke_privileges(user, group)
 	if nixio.getuid() == 0 then
 		return nixio.setgid(group) and nixio.setuid(user)
 	end
 end
 
+--- Return a secure UCI cursor.
+-- @return UCI cursor
 function securestate()
 	local stat = nixio.fs.stat(SSTATE) or {}
 	local uid = nixio.getuid()
@@ -253,6 +294,8 @@ function securestate()
 	return uci.cursor(nil, SSTATE)
 end
 
+--- Daemonize the process.
+-- @return boolean status or nil, error code, error message
 function daemonize()
 	if nixio.getppid() == 1 then
 		return
diff --git a/libs/lucid/luasrc/lucid/tcpserver.lua b/libs/lucid/luasrc/lucid/tcpserver.lua
index b1b95c1fb..2897ec8ea 100644
--- a/libs/lucid/luasrc/lucid/tcpserver.lua
+++ b/libs/lucid/luasrc/lucid/tcpserver.lua
@@ -28,7 +28,10 @@ local UCINAME = lucid.UCINAME
 
 local tcpsockets = {}
 
-
+--- Prepare a daemon and allocate its resources. (superserver callback)
+-- @param config configuration table
+-- @param server LuCId basemodule
+-- @return binary data
 function prepare_daemon(config, server)
 	nixio.syslog("info", "Preparing TCP-Daemon " .. config[".name"])
 	if type(config.address) ~= "table" then
@@ -104,6 +107,9 @@ function prepare_daemon(config, server)
 	end
 end
 
+--- Accept a new TCP connection. (server callback)
+-- @param polle Poll descriptor
+-- @return handler process id or nil, error code, error message 
 function accept(polle)
 	local socket, host, port = polle.fd:accept()
 	if not socket then
@@ -133,6 +139,13 @@ function accept(polle)
 	return unpack(stat)
 end
 
+--- Prepare a TCP server socket.
+-- @param family protocol family ["inetany", "inet6", "inet"]
+-- @param host host
+-- @param port port
+-- @param opts table of socket options
+-- @param backlog socket backlog
+-- @return socket, final socket family
 function prepare_socket(family, host, port, opts, backlog)
 	nixio.syslog("info", "Preparing socket for port " .. port)
 	backlog = backlog or 1024
@@ -171,6 +184,10 @@ function prepare_socket(family, host, port, opts, backlog)
 	return socket, family
 end
 
+--- Prepare a TLS server context and load keys and certificates.
+-- May invoke px5g to create keys and certificate on demand if available.
+-- @param tlskey TLS configuration identifier
+-- @return TLS server conext or nil
 function prepare_tls(tlskey)
 	local tls
 	if tlskey and cursor:get(UCINAME, tlskey) then