Cleanup and documentation

1 files changed, 93 insertions, 16 deletions

diff --git a/libs/core/luasrc/ltn12.lua b/libs/core/luasrc/ltn12.lua
index a6ce11bf1..c9b663463 100644
--- a/libs/core/luasrc/ltn12.lua
+++ b/libs/core/luasrc/ltn12.lua
@@ -20,6 +20,11 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 ]]--
+--[[
+	Changes made by LuCI project:
+		* Renamed to luci.ltn12 to avoid collisions with luasocket
+		* Added inline documentation
+]]--
 -----------------------------------------------------------------------------
 -- LTN12 - Filters, sources, sinks and pumps.
 -- LuaSocket toolkit.
@@ -33,6 +38,9 @@ DEALINGS IN THE SOFTWARE.
 local string = require("string")
 local table = require("table")
 local base = _G
+
+--- Diego Nehab's LTN12 - Filters, sources, sinks and pumps.
+-- See http://lua-users.org/wiki/FiltersSourcesAndSinks for design concepts 
 module("luci.ltn12")
 
 filter = {}
@@ -47,7 +55,17 @@ _VERSION = "LTN12 1.0.1"
 -----------------------------------------------------------------------------
 -- Filter stuff
 -----------------------------------------------------------------------------
--- returns a high level filter that cycles a low-level filter
+
+--- LTN12 Filter constructors
+-- @class module
+-- @name luci.ltn12.filter
+
+--- Return a high level filter that cycles a low-level filter
+-- by passing it each chunk and updating a context between calls. 
+-- @param low   Low-level filter
+-- @param ctx   Context
+-- @param extra Extra argument passed to the low-level filter
+-- @return LTN12 filter
 function filter.cycle(low, ctx, extra)
     base.assert(low)
     return function(chunk)
@@ -57,8 +75,10 @@ function filter.cycle(low, ctx, extra)
     end
 end
 
--- chains a bunch of filters together
+--- Chain a bunch of filters together.
 -- (thanks to Wim Couwenberg)
+-- @param ... filters to be chained
+-- @return LTN12 filter
 function filter.chain(...)
     local n = table.getn(arg)
     local top, index = 1, 1
@@ -91,23 +111,35 @@ end
 -----------------------------------------------------------------------------
 -- Source stuff
 -----------------------------------------------------------------------------
+
+--- LTN12 Source constructors
+-- @class module
+-- @name luci.ltn12.source
+
 -- create an empty source
 local function empty()
     return nil
 end
 
+--- Create an empty source.
+-- @return LTN12 source
 function source.empty()
     return empty
 end
 
--- returns a source that just outputs an error
+--- Return a source that just outputs an error.
+-- @param err Error object
+-- @return LTN12 source
 function source.error(err)
     return function()
         return nil, err
     end
 end
 
--- creates a file source
+--- Create a file source.
+-- @param handle File handle ready for reading
+-- @param io_err IO error object
+-- @return LTN12 source
 function source.file(handle, io_err)
     if handle then
         return function()
@@ -118,7 +150,9 @@ function source.file(handle, io_err)
     else return source.error(io_err or "unable to open file") end
 end
 
--- turns a fancy source into a simple source
+--- Turn a fancy source into a simple source.
+-- @param src fancy source
+-- @return LTN12 source
 function source.simplify(src)
     base.assert(src)
     return function()
@@ -129,7 +163,9 @@ function source.simplify(src)
     end
 end
 
--- creates string source
+--- Create a string source.
+-- @param s Data
+-- @return LTN12 source
 function source.string(s)
     if s then
         local i = 1
@@ -142,7 +178,9 @@ function source.string(s)
     else return source.empty() end
 end
 
--- creates rewindable source
+--- Creates rewindable source.
+-- @param src LTN12 source to be made rewindable
+-- @return LTN12 source
 function source.rewind(src)
     base.assert(src)
     local t = {}
@@ -157,6 +195,10 @@ function source.rewind(src)
     end
 end
 
+--- Chain a source and a filter together.
+-- @param src LTN12 source
+-- @param f LTN12 filter
+-- @return LTN12 source
 function source.chain(src, f)
     base.assert(src and f)
     local last_in, last_out = "", ""
@@ -204,9 +246,11 @@ function source.chain(src, f)
     end
 end
 
--- creates a source that produces contents of several sources, one after the
--- other, as if they were concatenated
+--- Create a source that produces contents of several sources.
+-- Sources will be used one after the other, as if they were concatenated
 -- (thanks to Wim Couwenberg)
+-- @param ... LTN12 sources
+-- @return LTN12 source
 function source.cat(...)
     local src = table.remove(arg, 1)
     return function()
@@ -222,7 +266,14 @@ end
 -----------------------------------------------------------------------------
 -- Sink stuff
 -----------------------------------------------------------------------------
--- creates a sink that stores into a table
+
+--- LTN12 sink constructors
+-- @class module
+-- @name luci.ltn12.sink
+
+--- Create a sink that stores into a table.
+-- @param t output table to store into
+-- @return LTN12 sink
 function sink.table(t)
     t = t or {}
     local f = function(chunk, err)
@@ -232,7 +283,9 @@ function sink.table(t)
     return f, t
 end
 
--- turns a fancy sink into a simple sink
+--- Turn a fancy sink into a simple sink.
+-- @param snk fancy sink
+-- @return LTN12 sink
 function sink.simplify(snk)
     base.assert(snk)
     return function(chunk, err)
@@ -243,7 +296,10 @@ function sink.simplify(snk)
     end
 end
 
--- creates a file sink
+--- Create a file sink.
+-- @param handle file handle to write to
+-- @param io_err IO error
+-- @return LTN12 sink
 function sink.file(handle, io_err)
     if handle then
         return function(chunk, err)
@@ -260,18 +316,25 @@ local function null()
     return 1
 end
 
+--- Create a sink that discards data.
+-- @return LTN12 sink
 function sink.null()
     return null
 end
 
--- creates a sink that just returns an error
+--- Create a sink that just returns an error.
+-- @param err Error object
+-- @return LTN12 sink
 function sink.error(err)
     return function()
         return nil, err
     end
 end
 
--- chains a sink with a filter
+--- Chain a sink with a filter.
+-- @param f LTN12 filter
+-- @param snk LTN12 sink
+-- @return LTN12 sink
 function sink.chain(f, snk)
     base.assert(f and snk)
     return function(chunk, err)
@@ -291,7 +354,16 @@ end
 -----------------------------------------------------------------------------
 -- Pump stuff
 -----------------------------------------------------------------------------
--- pumps one chunk from the source to the sink
+
+--- LTN12 pump functions
+-- @class module
+-- @name luci.ltn12.pump
+
+--- Pump one chunk from the source to the sink.
+-- @param src LTN12 source
+-- @param snk LTN12 sink
+-- @return Chunk of data or nil if an error occured
+-- @return Error object
 function pump.step(src, snk)
     local chunk, src_err = src()
     local ret, snk_err = snk(chunk, src_err)
@@ -299,7 +371,12 @@ function pump.step(src, snk)
     else return nil, src_err or snk_err end
 end
 
--- pumps all data from a source to a sink, using a step function
+--- Pump all data from a source to a sink, using a step function.
+-- @param src LTN12 source
+-- @param snk LTN12 sink
+-- @param step step function (optional)
+-- @return 1 if the operation succeeded otherwise nil
+-- @return Error object
 function pump.all(src, snk, step)
     base.assert(src and snk)
     step = step or pump.step