GSoC: Documentation #2

4 files changed, 102 insertions, 7 deletions

diff --git a/libs/lucid-rpc/luasrc/lucid/rpc.lua b/libs/lucid-rpc/luasrc/lucid/rpc.lua
index c89fc24442..417e572142 100644
--- a/libs/lucid-rpc/luasrc/lucid/rpc.lua
+++ b/libs/lucid-rpc/luasrc/lucid/rpc.lua
@@ -17,7 +17,9 @@ local srv = require "luci.lucid.rpc.server"
 
 module "luci.lucid.rpc"
 
-
+--- Prepare the RPC-daemon and its associated publishers.
+-- @param publisher Table of publishers
+-- @return factory callback or nil, error message
 function factory(publisher)
 	local root = srv.Module()
 	local server = srv.Server(root)
diff --git a/libs/lucid-rpc/luasrc/lucid/rpc/ruci.lua b/libs/lucid-rpc/luasrc/lucid/rpc/ruci.lua
index 38e57f3667..f0910c7f0b 100644
--- a/libs/lucid-rpc/luasrc/lucid/rpc/ruci.lua
+++ b/libs/lucid-rpc/luasrc/lucid/rpc/ruci.lua
@@ -16,8 +16,10 @@ local error, type = error, type
 local nixio = require "nixio"
 local srv = require "luci.lucid.rpc.server"
 
+--- Remote UCI functions.
 module "luci.lucid.rpc.ruci"
 
+-- Prepare the remote UCI functions.
 function _factory()
 	local m = srv.Module("Remote UCI API")
 	
@@ -30,10 +32,12 @@ function _factory()
 	return m
 end
 
+-- Get the associate RUCI instance.
 local function getinst(session, name)
 	return session.ruci and session.ruci[name]
 end
 
+-- Set a new RUCI instance.
 local function setinst(session, obj)
 	session.ruci = session.ruci or {}
 	local name = tostring(obj):match("0x([a-z0-9]+)")
@@ -41,6 +45,7 @@ local function setinst(session, obj)
 	return name
 end
 
+
 local Cursor = getmetatable(uci.cursor())
 
 for name, func in pairs(Cursor) do
@@ -50,14 +55,28 @@ for name, func in pairs(Cursor) do
 	end
 end
 
+--- Generate a new RUCI cursor.
+-- @param session Session object
+-- @param ... Parameters passed to the UCI constructor
+-- @return RUCI instance
 function cursor(session, ...)
 	return setinst(session, uci.cursor(...))
 end
 
+--- Generate a new RUCI state cursor.
+-- @param session Session object
+-- @param ... Parameters passed to the UCI constructor
+-- @return RUCI instance
 function cursor_state(session, ...)
 	return setinst(session, uci.cursor_state(...))
 end
 
+--- Custom foreach function.
+-- @param session Session object
+-- @param inst RUCI instance
+-- @param config UCI config
+-- @param sectiontype UCI sectiontype
+-- @return section data
 function foreach(session, inst, config, sectiontype)
 	local inst = getinst(session, inst)
 	local secs = {}
diff --git a/libs/lucid-rpc/luasrc/lucid/rpc/server.lua b/libs/lucid-rpc/luasrc/lucid/rpc/server.lua
index af25280d9d..18b004d8b8 100644
--- a/libs/lucid-rpc/luasrc/lucid/rpc/server.lua
+++ b/libs/lucid-rpc/luasrc/lucid/rpc/server.lua
@@ -22,6 +22,8 @@ local util = require "luci.util"
 local table = require "table"
 local ltn12 = require "luci.ltn12"
 
+--- RPC daemom.
+-- @cstyle instance
 module "luci.lucid.rpc.server"
 
 RQLIMIT = 32 * nixio.const.buffersize
@@ -48,9 +50,18 @@ ERRMSG = {
 }
 
 
-
+--- Create an RPC method wrapper.
+-- @class function
+-- @param method Lua function
+-- @param description Method description
+-- @return Wrapped RPC method 
 Method = util.class()
 
+--- Create an extended wrapped RPC method.
+-- @class function
+-- @param method Lua function
+-- @param description Method description
+-- @return Wrapped RPC method 
 function Method.extended(...)
 	local m = Method(...)
 	m.call = m.xcall
@@ -62,14 +73,26 @@ function Method.__init__(self, method, description)
 	self.method = method
 end
 
+--- Extended call the associated function.
+-- @param session Session storage
+-- @param argv Request parameters
+-- @return function call response
 function Method.xcall(self, session, argv)
 	return self.method(session, unpack(argv))
 end
 
+--- Standard call the associated function.
+-- @param session Session storage
+-- @param argv Request parameters
+-- @return function call response
 function Method.call(self, session, argv)
 	return self.method(unpack(argv))
 end
 
+--- Process a given request and create a JSON response.
+-- @param session Session storage
+-- @param request Requested method
+-- @param argv Request parameters
 function Method.process(self, session, request, argv)
 	local stat, result = pcall(self.call, self, session, argv)
 	
@@ -84,7 +107,7 @@ function Method.process(self, session, request, argv)
 	end
 end
 
-
+-- Remap IPv6-IPv4-compatibility addresses to IPv4 addresses
 local function remapipv6(adr)
 	local map = "::ffff:"
 	if adr:sub(1, #map) == map then
@@ -94,6 +117,11 @@ local function remapipv6(adr)
 	end 
 end
 
+
+--- Create an RPC module.
+-- @class function
+-- @param description Method description
+-- @return RPC module 
 Module = util.class()
 
 function Module.__init__(self, description)
@@ -101,11 +129,15 @@ function Module.__init__(self, description)
 	self.handler = {}
 end
 
+--- Add a handler.
+-- @param k key
+-- @param v handler
 function Module.add(self, k, v)
 	self.handler[k] = v
 end
 
--- Access Restrictions
+--- Add an access restriction.
+-- @param restriction Restriction specification
 function Module.restrict(self, restriction)
 	if not self.restrictions then
 		self.restrictions = {restriction}
@@ -114,7 +146,9 @@ function Module.restrict(self, restriction)
 	end
 end
 
--- Check restrictions
+--- Enforce access restrictions.
+-- @param request Request object
+-- @return nil or HTTP statuscode, table of headers, response source
 function Module.checkrestricted(self, session, request, argv)
 	if not self.restrictions then
 		return
@@ -149,6 +183,10 @@ function Module.checkrestricted(self, session, request, argv)
 	return {error={code=ERRNO_NOACCESS, message=ERRMSG[ERRNO_NOACCESS]}}
 end
 
+--- Register a handler, submodule or function.
+-- @param m entity
+-- @param descr description
+-- @return Module (self)
 function Module.register(self, m, descr)
 	descr = descr or {}
 	for k, v in pairs(m) do
@@ -164,6 +202,11 @@ function Module.register(self, m, descr)
 	return self
 end
 
+--- Process a request.
+-- @param session Session storage
+-- @param request Request object
+-- @param argv Request parameters
+-- @return JSON response object
 function Module.process(self, session, request, argv)
 	local first, last = request:match("^([^.]+).?(.*)$")
 
@@ -182,21 +225,34 @@ function Module.process(self, session, request, argv)
 end
 
 
-
+--- Create a server object.
+-- @class function
+-- @param root Root module
+-- @return Server object
 Server = util.class()
 
 function Server.__init__(self, root)
 	self.root = root
 end
 
+--- Get the associated root module.
+-- @return Root module
 function Server.get_root(self)
 	return self.root
 end
 
+--- Set a new root module.
+-- @param root Root module
 function Server.set_root(self, root)
 	self.root = root
 end
 
+--- Create a JSON reply.
+-- @param jsonrpc JSON-RPC version
+-- @param id Message id
+-- @param res Result
+-- @param err Error
+-- @reutrn JSON response source
 function Server.reply(self, jsonrpc, id, res, err)
 	id = id or json.null
 	
@@ -212,6 +268,9 @@ function Server.reply(self, jsonrpc, id, res, err)
 		):source()
 end
 
+--- Handle a new client connection.
+-- @param client client socket
+-- @param env superserver environment
 function Server.process(self, client, env)
 	local decoder
 	local sinkout = client:sink()
diff --git a/libs/lucid-rpc/luasrc/lucid/rpc/system.lua b/libs/lucid-rpc/luasrc/lucid/rpc/system.lua
index 4f7f0b5c29..cf3aa6abe4 100644
--- a/libs/lucid-rpc/luasrc/lucid/rpc/system.lua
+++ b/libs/lucid-rpc/luasrc/lucid/rpc/system.lua
@@ -17,8 +17,10 @@ local srv = require "luci.lucid.rpc.server"
 local nixio = require "nixio"
 local lucid = require "luci.lucid"
 
+--- Internal system functions.
 module "luci.lucid.rpc.system"
 
+-- Prepare the RPC module.
 function _factory()
 	local mod = srv.Module("System functions"):register({
 		echo = echo,
@@ -34,15 +36,22 @@ function _factory()
 	return mod
 end
 
-
+--- Simple echo test function.
+-- @param object to be echoed object
+-- @return echo object
 function echo(object)
 	return object
 end
 
+--- Simple void test function.
 function void()
 
 end
 
+--- Accumulate different requests and execute them.
+-- @param session Session object
+-- @param ...
+-- @return overall response object
 function multicall(session, ...)
 	local server, responses, response = session.server, {}, nil
 	for k, req in ipairs({...}) do
@@ -69,6 +78,12 @@ function multicall(session, ...)
 	return responses
 end
 
+--- Create or use a new authentication token.
+-- @param session Session object
+-- @param type Authentication type
+-- @param entity Authentication enttity (username)
+-- @param key Authentication key (password)
+-- @return boolean status
 function authenticate(session, type, entity, key)
 	if not type then
 		session.user = nil