More documentation, start on luxio.simple docs.

4 files changed, 98 insertions, 6 deletions

diff --git a/.bzrignore b/.bzrignore
index 0d1ab25..06ce2ae 100644
--- a/.bzrignore
+++ b/.bzrignore
@@ -3,3 +3,4 @@ luxio-5.1
 luxio-5.2
 doc/index.html
 doc/ldoc.css
+doc/modules
diff --git a/config.ld b/config.ld
index fb45794..ac2d734 100644
--- a/config.ld
+++ b/config.ld
@@ -1,4 +1,4 @@
-file = { "luxio.c" }
+file = { "luxio.c", "luxio/simple.lua" }
 format = "discount"
 project = "Luxio Light UNIX I/O"
 title = project
diff --git a/luxio.c b/luxio.c
index 24ec720..8c1a2c6 100644
--- a/luxio.c
+++ b/luxio.c
@@ -3539,7 +3539,7 @@ luxio_gettimeofday(lua_State *L)
 */
 
 /*** Return a string describing an error number.
-@tparam errno
+@tparam errno errno
 @treturn string
 @function strerror
 */
@@ -3666,7 +3666,7 @@ luxio_iconv_open(lua_State *L)
 }
 
 /*** Close a previously-allocated iconv descriptor.
-@tparam iconv
+@tparam iconv handle
 @treturn number return vlaue
 @treturn errno
 @function iconv_close
@@ -3689,8 +3689,8 @@ luxio_iconv_close(lua_State *L)
 #define ICONV_BUF_SIZE 256
 
 /*** Perform character set conversion.
-@tparam iconv
-@tparam string
+@tparam iconv handle
+@tparam string buf
 @treturn string|number resulting string or return value in case of error
 @treturn errno
 @treturn string|nil partial result when error.
diff --git a/luxio/simple.lua b/luxio/simple.lua
index b5d99bd..09c6074 100644
--- a/luxio/simple.lua
+++ b/luxio/simple.lua
@@ -5,7 +5,10 @@
 --
 -- A wrapper around the rather raw interface luxio normally provides to
 -- make things simpler.
--------------------------------------------------------------------------------
+
+--- High-level bindings to POSIX functionality.
+--- @module luxio.simple
+
 --
 -- sio = require "luxio.simple"
 --
@@ -198,6 +201,12 @@
 --         For example, flags("rdrw,creat,excl") would be the same as ORing
 --         together O_RDWR, O_CREAT, and O_EXCL.
 
+--- A file handle.
+--- All files, be they ones in a file system, a pipe, or a socket, are
+--- accessed though this type.
+--- @type file
+--- @field number file descriptor
+
 local l = require "luxio"
 
 assert(l._ABI == 0, "luxio ABI mismatch")
@@ -320,6 +329,21 @@ end
 
 local flag_cache = { }
 
+--- Helper functions.
+--- @section helper
+
+--- Convert a string of comma-seperated flag names to a number.
+--- This function takes a list of strings, each with comma-seperated flag names
+--- and returns a number which is all of those flags ORed together.
+--- Flags can optionally be lower-case, and also if they begin with one of
+--- the common prefixes, such as O_, S_, F_, AF_, AI_, SO_, TCP_ and many others
+--- can be omitted.
+--- For example:
+---
+---     myflags = sio.flags "rdwr,creat,excl"
+--- @tparam string ...
+--- @treturn number
+--- @function flags
 local function flags(...)
     local r = 0
     local f = table.concat({ ... }, ",")
@@ -363,6 +387,17 @@ local S_IWALL = l_bit_bor(l.S_IWUSR, l.S_IWGRP, l.S_IWOTH)
 local S_IXALL = l_bit_bor(l.S_IXUSR, l.S_IXGRP, l.S_IXOTH)
 local S_ISUIDGID = l_bit_bor(l.S_ISUID, l.S_ISGID)
 
+--- Convert a string representing a permissions mode to a number.
+--- This function converts a string into a mode flag.  It supports
+--- many different forms.  For example:
+---
+---    sio.tomode(0666) -- already a mode, it'll just return it
+---    sio.tomode "666" -- converted directly to number, assumed octal
+---    sio.tomode "-rw-r--r--" -- as emitted by ls
+---    sio.tomode "o+rw,g+r" -- as used by chmod
+--- @tparam number|string f mode description to convert
+--- @treturn number
+--- @function tomode
 local function sio_mode_flags(f)
     if type(f) == "number" then
     -- is already a suitable mode
@@ -438,6 +473,27 @@ local function sio_open_flags(flags)
     return l_bit_bor(unpack(r))
 end
 
+--- Opening files.
+--- @section open
+
+--- Open a file.
+--- The open type may contain the following characters;
+---
+---   * r - open file for reading
+---   * w - open file for writing
+---   * \+ - append
+---   * e - open and create exclusively (O_EXCL and O_CREAT)
+---   * c - create file if it doesn't exist. (O_CREAT)
+---   * n - do not modify access time (O_NOATIME)
+---   * d - open in non-blocking mode (O_NDELAY)
+---   * t - truncate file
+--- @tparam string filename
+--- @tparam[opt="r"] string flags open type
+--- @tparam[opt] mode number permissions mode if creating.
+--- @treturn file|nil File handle, or nil if error
+--- @treturn string|nil Error string if error
+--- @treturn errno|nil Error number if error
+--- @function open
 local function open(filename, flags, mode)
     mode = mode or tonumber("666", 8)
     assert(type(filename) == "string", "filename string expected at #1")
@@ -453,6 +509,13 @@ end
 
 local pipe_count = 0
 
+--- Create an anonymous pipe.
+--- Returns two files, the first one can be used to read data written
+--- to the second.
+--- @treturn file|nil Reading half of pipe, or nil on error
+--- @treturn file|string Writing half of pipe, or string describing error
+--- @treturn errno|nil Error number if error
+--- @function pipe
 local function pipe()
     local fds = { }
     local r, errno = l_pipe(fds)
@@ -471,6 +534,13 @@ end
 
 local socketpair_count = 0
 
+--- Create an anonymous UNIX domain socket pair.
+--- Returns two files, which can be considered as each end of a bi-directional
+-- pipe.
+--- @treturn file|nil First socket of the pair, or nil on error
+--- @treturn file|string Second socket of the pair, or string describing error
+--- @treturn errno|nil Error number if error
+--- @function pipe
 local function socketpair(type)
     type = type or l.SOCK_STREAM
     local typen = type == l.SOCK_STREAM and "stream" or "datagram"
@@ -488,6 +558,12 @@ local function socketpair(type)
     return sio_wrap_mt(sv[1], false, spname1), sio_wrap_mt(sv[2], false, spname2)
 end
 
+--- Close an open file.
+--- @function file:close
+--- @within file
+--- @treturn bool|nil true on success, nil on failure
+--- @treturn string|nil string describing error
+--- @treturn errno|nil errno on error
 local function close(o)
     sio_check_mt(o)
 
@@ -502,12 +578,19 @@ local function close(o)
     return true
 end
 
+--- Disable garbage collection of a file.
+--- @function file:nogc
+--- @within file
 local function nogc(o)
     sio_check_mt(o)
 
     o.nogcfd = true
 end
 
+--- Set the non-blocking flag on a file.
+--- @function file:nonblocking
+--- @within file
+--- @tparam bool blocking true for non-blocking, false or nil for blocking.
 local function nonblocking(o, b)
     sio_check_mt(o)
 
@@ -537,6 +620,14 @@ local function nonblocking(o, b)
     end
 end
 
+--- Write data to a file.
+--- @function file:write
+--- @within file
+--- @tparam string data
+--- @tparam[opt=1] number offset into string to start write from
+--- @treturn number|nil bytes written, or nil on error
+--- @treturn string|nil string describing error if error
+--- @treturn errno|nil errno if error
 local function write(o, d, i)
     sio_check_mt(o)
     assert(type(d) == "string", "string expected at #2")