More ldoc

1 files changed, 182 insertions, 95 deletions

diff --git a/luxio.c b/luxio.c
index 033e9a8..f56bc81 100644
--- a/luxio.c
+++ b/luxio.c
@@ -1177,9 +1177,9 @@ Returned by @{stat} and family.
 @field size total size, in bytes
 @field blksize blocksize for file system I/O
 @field blocks number of blocks allocated
-@atime time of last access
-@mtime time of last modification
-@ctime time of last status change
+@field atime time of last access
+@field mtime time of last modification
+@field ctime time of last status change
 @table stat-table
 */
 
@@ -1388,7 +1388,7 @@ luxio_fchmod(lua_State *L) /* 5.6.4 */
 /*** Change ownership of a file.
 @tparam string path
 @tparam number owner
-@tprarm number group
+@tparam number group
 @treturn number return value
 @treturn errno
 @function chmod
@@ -1410,7 +1410,7 @@ luxio_chown(lua_State *L) /* 5.6.5 */
 
 /*** Truncate a file to a specified length.
 @tparam number fd
-@tparamnumber lenght
+@tparam number lenght
 @treturn number return value
 @treturn errno
 @function ftruncate
@@ -1431,12 +1431,16 @@ luxio_ftruncate(lua_State *L) /* 5.6.7 */
 
 /* TODO: pathconf(), fpathconf() 5.7.1 */
 
-/**# Pipes *******************************************************************/
+/*** Pipes
+@section pipes
+*/
 
-/**% pipe
- * retval = pipe(pipearray);
- * retval, errno = pipe(pipetable) -- fills in [1] and [2] in pipetable
- */
+/*** Create pipe.
+@tparam table pipe A table for which this function will fill in the keys 1 and 2
+@treturn number return value
+@treturn errno
+@function pipe
+*/
 static int
 luxio_pipe(lua_State *L) /* 6.1.1 */
 {
@@ -1459,10 +1463,14 @@ luxio_pipe(lua_State *L) /* 6.1.1 */
 
 #ifdef _GNU_SOURCE
 
-/**% pipe2
- * retval = pipe2(pipearray, flags);
- * retval, errno = pipe2(pipetable, flags) -- fills in [1] and [2] in pipetable
- */
+/*** Create a pipe, with flags.
+Not available on all systems.
+@tparam table pipe A table for which this function will fill in the keys 1 and 2
+@tparam number flags
+@treturn number return value
+@treturn errno
+@function pipe2
+*/
 static int
 luxio_pipe2(lua_State *L) /* GNU extension */
 {
@@ -1487,10 +1495,15 @@ luxio_pipe2(lua_State *L) /* GNU extension */
 }
 #endif
 
-/**% socketpair
- * retval = socketpair(domain, type, protocol, fdarray)
- * retval, errno = socketpair(domain, type, protocol, fdtable)
- */
+/*** Create a pair of connected sockets.
+@tparam number domain
+@tparam number type
+@tparam number protocol
+@tparam table fdarray The values [1] and [2] are filled in with descriptors
+@treturn number return value
+@treturn errno
+@function socketpair
+*/
 static int
 luxio_socketpair(lua_State *L) /* POSIX.1-2001 */
 {
@@ -1515,12 +1528,16 @@ luxio_socketpair(lua_State *L) /* POSIX.1-2001 */
 	return 2;
 }
 
-/**# File descriptor manipulation ********************************************/
+/*** File descriptor manipulation.
+@section fdmanip
+*/
 
-/**% dup
- * retval = dup(oldfd);
- * retval, errno = dup(oldfd)
- */
+/*** Duplicate a file descriptor.
+@tparam number oldfd
+@treturn number return value
+@treturn errno
+@function dup
+*/
 static int
 luxio_dup(lua_State *L) /* 6.2.1 */
 {
@@ -1532,10 +1549,13 @@ luxio_dup(lua_State *L) /* 6.2.1 */
 	return 2;
 }
 
-/**% dup2
- * retval = dup2(oldfd, newfd);
- * retval, errno = dup2(oldfd, newfd)
- */
+/*** Duplicate a file descriptor to a specific one
+@tparam number oldfd
+@tparam number newfd
+@treturn number return value
+@treturn errno
+@function dup2
+*/
 static int
 luxio_dup2(lua_State *L) /* 6.2.1 */
 {
@@ -1549,10 +1569,15 @@ luxio_dup2(lua_State *L) /* 6.2.1 */
 }
 
 #ifdef _GNU_SOURCE
-/**% dup3
- * retval = dup3(oldfd, newfd, flags);
- * retval, errno = dup2(oldfd, newfd, flags)
- */
+/** Duplicate a file descriptor to a specific one, with flags.
+Not available on all platforms.
+@tparam number oldfd
+@tparam number newfd
+@tparam number flags
+@treturn number return value
+@treturn errno
+@function dup3
+*/
 static int
 luxio_dup3(lua_State *L) /* GNU extension */
 {
@@ -1567,12 +1592,16 @@ luxio_dup3(lua_State *L) /* GNU extension */
 }
 #endif
 
-/**# File descriptor deassignment ********************************************/
+/*** File descriptor deassignment.
+@section fileclose
+*/
 
-/**% close
- * retval = close(fd);
- * retval, errno = close(fd)
- */
+/*** Close a file descriptor.
+@tparam number fd
+@treturn number return value
+@treturn errno
+@function close
+*/
 static int
 luxio_close(lua_State *L) /* 6.3.1 */
 {
@@ -1582,13 +1611,17 @@ luxio_close(lua_State *L) /* 6.3.1 */
 	return 2;
 }
 
-/**# Input and output ********************************************************/
+/*** Input and output
+@section io
+*/
 
-/**% read
- * retval = read(fd, buf, count);
- * retval, errno = read(fd, count)
- * string, errno = read(fd, count)
- */
+/*** Read from a file descriptor.
+@tparam number fd
+@tparam number count
+@treturn number|string return value or read data
+@treturn errno
+@function read
+*/
 static int
 luxio_read(lua_State *L) /* 6.4.1 */
 {
@@ -1625,10 +1658,14 @@ luxio_read(lua_State *L) /* 6.4.1 */
     return 2;
 }
 
-/**% write
- * retval = write(fd, buf, count);
- * retval, errno = write(fd, string[, start_offset/0])
- */
+/*** Write to a file descriptor.
+@tparam number fd
+@tparam string data
+@tparam[opt=0] number start_offset
+@treturn number return value
+@treturn errno
+@function write
+*/
 static int
 luxio_write(lua_State *L) /* 6.4.2 */
 {
@@ -1645,10 +1682,13 @@ luxio_write(lua_State *L) /* 6.4.2 */
 	return 2;
 }
 
-/**% writev
- * retval = writev(fd, iov, blks);
- * retval, errno = writev(fd, string[, ...])
- */
+/*** Write data from multiple buffers.
+@tparam number fd
+@tparam string ...
+@treturn number return value
+@treturn errno
+@function writev
+*/
 static int
 luxio_writev(lua_State *L) /* POSIX.1-2001 */
 {
@@ -1676,10 +1716,16 @@ luxio_writev(lua_State *L) /* POSIX.1-2001 */
 }
 
 #ifdef HAVE_SENDFILE
-/**% sendfile
- * retval = sendfile(out_fd, in_fd, offset/NULL, count);
- * retval, errno = sendfile(out_fd, in_fd, offset/nil, count)
- */
+/*** Transfer data between descriptors.
+Not available on all systems.
+@tparam number out_fd
+@tparam number in_fd
+@tparam[opt=nil] number offset
+@tparam number count
+@treturn number return value
+@treturn errno
+@function sendfile
+*/
 static int
 luxio_sendfile(lua_State *L) /* Linux-specific */
 {
@@ -1707,10 +1753,18 @@ luxio_sendfile(lua_State *L) /* Linux-specific */
 #endif /* HAVE_SENDFILE */
 
 #ifdef HAVE_SPLICE
-/**% splice
- * retval = splice(fd_in, off_in, fd_out, off_out, len, flags);
- * retval, errno = splice(fd_in, off_in, fd_out, off_out, len, flags)
- */
+/*** Splice data to or from a pipe.
+Not available on all systems.
+@tparam number fd_in
+@tparam number off_in
+@tparam number fd_out
+@tparam number off_out
+@tparam number len
+@tparam number flags
+@treturn number return value
+@treturn errno
+@function splice
+*/
 static int
 luxio_splice(lua_State *L) /* Linux-specific */
 {
@@ -1735,17 +1789,25 @@ luxio_splice(lua_State *L) /* Linux-specific */
 }
 #endif
 
-/**# Control operations on files *********************************************/
+/*** Control operations on files
+@section fcntl
+*/
 
-/**> fcntl
- * Supported commands:
- *  F_GETFD/F_SETFD, F_GETFL/F_SETFL, F_GETPIPE_SZ/F_SETPIPE_SZ, F_DUPFD,
- *  F_DUPFD_CLOEXEC, F_SETLK, F_SETLKW, F_GETLK
- *
- * C-Style: retval = fcntl(fd, cmd[, argument]);
- *
- * Lua-Style: retval, errno = fcntl(fd, cmd[, argument])
- */
+/*** Manipulate file descriptor.
+Supported commands: F_GETFD/F_SETFD, F_GETFL/F_SETFL,
+F_GETPIPE_SZ/F_SETPIPE_SZ, F_DUPFD, F_DUPFD_CLOEXEC,
+F_SETLK, F_SETLKW, F_GETLK.
+
+Commands that take a struct, such as F_SETLK, accept
+a table as the argument, with keys named as the struct's.
+
+@tparam number fd
+@tparam number command
+@tparam ... ...
+@treturn number return value
+@treturn errno
+@function fcntl
+*/
 static int
 luxio_fcntl(lua_State *L) /* 6.5.2 */
 {
@@ -1837,10 +1899,14 @@ luxio_lseek(lua_State *L) /* 6.5.3 */
 	return 2;
 }
 #else
-/**% lseek
- * retval = lseek(fd, offset, whence);
- * retval, errno = lseek(fd, offset, whence)
- */
+/*** Reposition read/write file offset.
+@tparam number fd
+@tparam number offset
+@tparam number whence
+@treturn number return value
+@treturn errno
+@function lseek
+*/
 static int
 luxio_lseek(lua_State *L) /* 6.5.3 */
 {
@@ -1855,12 +1921,16 @@ luxio_lseek(lua_State *L) /* 6.5.3 */
 }
 #endif
 
-/**# File synchronisation ****************************************************/
+/*** File synchronisation.
+@section filesync
+*/
 
-/**% fsync
- * retval = fsync(filedes);
- * retval, errno = fsync(filedes)
- */
+/*** Synchronise a file's in-core state with storage device.
+@tparam number fd
+@treturn number return value
+@treturn errno
+@function fsync
+*/
 static int
 luxio_fsync(lua_State *L) /* 6.6.1 */
 {
@@ -1873,10 +1943,13 @@ luxio_fsync(lua_State *L) /* 6.6.1 */
 }
 
 #ifdef HAVE_FDATASYNC
-/**% fdatasync
- * retval = fdatasync(filedes);
- * retval = fdatasync(filedes)
- */
+/*** Synchronise only a file's data and not unnessercery metadata.
+Not available on all systems.
+@tparam number fd
+@treturn number return value
+@treturn errno
+@function fdatasync
+*/
 static int
 luxio_fdatasync(lua_State *L) /* 6.6.2 */
 {
@@ -1900,16 +1973,20 @@ luxio_fdatasync(lua_State *L) /* 6.6.2 */
 /* TODO: aio_suspend() 6.7.8 */
 /* TODO: aio_fsync() 6.7.9 */
 
-/**# General Terminal Interface **********************************************/
+/*** General Terminal Interface.
+@section genterm
+*/
 
 /* TODO: cfgetispeed(), cfgetospeed(), cfsetispeed(), cfsetospeed() 7.1.3 */
 /* TODO: tcgetattr(), tcsetattr() 7.2.1 */
 /* TODO: tcsendbreak(), tcdrain(), tcflush(), tcflow() 7.2.2 */
 
-/**% tcgetpgrp
- * retval = tcgetpgrp(filedes);
- * retval, errno = tcgetpgrp(filedes)
- */
+/*** Get terminal forground process group.
+@tparam number fd
+@treturn number return value
+@treturn errno
+@function tcgetpgrp
+*/
 static int
 luxio_tcgetpgrp(lua_State *L) /* 7.2.3 */
 {
@@ -1919,10 +1996,13 @@ luxio_tcgetpgrp(lua_State *L) /* 7.2.3 */
 	return 2;
 }
 
-/**% tcsetpgrp
- * retval = tcsetpgrp(filedes, pgrp_id);
- * retval = tcsetpgrp(filedes, pgrp_id)
- */
+/*** Set terminal forground process group.
+@tparam number fd
+@tparam number pgrp_id
+@treturn number return value
+@treturn errno
+@function tcsetpgrp
+*/
 static int
 luxio_tcsetpgrp(lua_State *L) /* 7.2.4 */
 {
@@ -1962,15 +2042,22 @@ luxio_tcsetpgrp(lua_State *L) /* 7.2.4 */
 
 /* TODO: all of this. */
 
-/**# Clock and timer functions ***********************************************/
+/*** Clock and timer functions.
+@section clocktimer
+*/
 
 /* TODO: clock_settime(), clock_gettime(), clock_getres() 14.2.1 */
 /* Timer functions excluded, based on signals */
 
-/**% nanosleep
- * retval = nanosleep(req_timespec, rem_timespec);
- * retval, errno, rem_sec, rem_nsec = nanosleep(req_sec, req_nsec)
- */
+/*** High-resolution sleep.
+@tparam number seconds
+@tparam number nanoseconds
+@treturn number return value
+@treturn errno
+@treturn number remaining seconds
+@treturn number remaining nanosections
+@function nanosleep
+*/
 static int
 luxio_nanosleep(lua_State *L) /* 14.2.5 */
 {