More ldoc

1 files changed, 141 insertions, 89 deletions

diff --git a/luxio.c b/luxio.c
index 0da3270..42a922a 100644
--- a/luxio.c
+++ b/luxio.c
@@ -397,12 +397,14 @@ luxio_getppid(lua_State *L) /* 4.1.1 */
 	return 1;
 }
 
-/**# User identification *****************************************************/
+/*** User identification.
+@section userident
+*/
 
-/**% getuid
- *  retval = getuid();
- *  retval = getuid()
- */
+/*** Get user identity.
+@treturn number uid
+@function getuid
+*/
 static int
 luxio_getuid(lua_State *L) /* 4.2.1 */
 {
@@ -411,10 +413,10 @@ luxio_getuid(lua_State *L) /* 4.2.1 */
 	return 1;
 }
 
-/**% geteuid
- *  retval = geteuid();
- *  retval = geteuid()
- */
+/*** Get effective user identity.
+@treturn number uid
+@function geteuid
+*/
 static int
 luxio_geteuid(lua_State *L) /* 4.2.1 */
 {
@@ -423,10 +425,10 @@ luxio_geteuid(lua_State *L) /* 4.2.1 */
 	return 1;
 }
 
-/**% getgid
- *  retval = getgid();
- *  retval = getgid()
- */
+/*** Get group identity.
+@treturn number gid
+@function getgid
+*/
 static int
 luxio_getgid(lua_State *L) /* 4.2.1 */
 {
@@ -435,10 +437,10 @@ luxio_getgid(lua_State *L) /* 4.2.1 */
 	return 1;
 }
 
-/**% getegid
- *  retval = getegid();
- *  retval = getegid()
- */
+/*** Get effective group identity.
+@treturn number gid
+@function getegid
+*/
 static int
 luxio_getegid(lua_State *L) /* 4.2.1 */
 {
@@ -447,10 +449,12 @@ luxio_getegid(lua_State *L) /* 4.2.1 */
 	return 1;
 }
 
-/**% setuid
- *  retval = setuid(uid);
- *  retval, errno = setuid(uid)
- */
+/*** Set user identity.
+@tparam number uid
+@treturn number return value
+@treturn errno errno
+@function setuid
+*/
 static int
 luxio_setuid(lua_State *L) /* 4.2.2 */
 {
@@ -462,10 +466,12 @@ luxio_setuid(lua_State *L) /* 4.2.2 */
 	return 2;
 }
 
-/**% setgid
- *  retval = setgid(gid);
- *  retval, errno = setgid(gid)
- */
+/*** Set group identity
+@tparam number gid
+@treturn number return value
+@treturn errno errno
+@function setgid
+*/
 static int
 luxio_setgid(lua_State *L) /* 4.2.2 */
 {
@@ -479,11 +485,11 @@ luxio_setgid(lua_State *L) /* 4.2.2 */
 
 /* TODO: getgroups() 4.2.3 */
 
-/**% getlogin
- *  retval = getlogin_r(buf, bufsize);
- *  retval, login = getlogin()
- *  retval, errno = getlogin()
- */
+/*** Get username.
+@treturn number return value
+@treturn string|errno username or errno
+@function getlogin
+*/
 static int
 luxio_getlogin(lua_State *L) /* 4.2.4 */
 {
@@ -503,19 +509,33 @@ luxio_getlogin(lua_State *L) /* 4.2.4 */
 	return 2;
 }
 
-/* 4.3 Process groups ********************************************************/
+/*** Process groups.
+@section procgroup
+*/
 
 /* TODO: getpgrp() 4.3.1 */
 /* TODO: setsid() 4.3.2 */
 /* TODO: setpgid() 4.3.3 */
 
-/**# System identification ***************************************************/
+/*** System identification.
+@section sysident
+*/
 
-/**% uname
- *  retval = uname(buf);
- *  retval, utsname = uname() -- A table containing struct fields
- *  retval, errno = uname()
- */
+/*** uname() information table.
+Returned by @{uname}.  Some fields are OS-specific.
+@field sysname Operating system name, such as Linux or NetBSD.
+@field nodename System's name
+@field release Operating systems's release version
+@field machine Hardware identifier
+@field domainname NIS or YP domain name
+@table uname-table
+*/
+
+/*** Get name and information about current kernel.
+@treturn number return value
+@treturn uname-table|errno result table, or errno.
+@function uname
+*/
 static int
 luxio_uname(lua_State *L) /* 4.4.1 */
 {
@@ -550,12 +570,15 @@ luxio_uname(lua_State *L) /* 4.4.1 */
 	return 2;
 }
 
-/**# Time ********************************************************************/
+/*** Time.
+@section time
+*/
 
-/**% time
- *  retval = time(NULL);
- *  retval, errno = time()
- */
+/*** Get time in seconds.
+@treturn number seconds since epoch.
+@treturn number errno
+@function time
+*/
 static int
 luxio_time(lua_State *L) /* 4.5.1 */
 {
@@ -565,11 +588,20 @@ luxio_time(lua_State *L) /* 4.5.1 */
 	return 2;
 }
 
-/**% times
- *  retval = times(buf);
- *  retval, tms = times() -- A table containing utime, stime, cutime, cstime
- *  retval, errno = times()
- */
+/*** times() information table.
+Returned by @{times}.
+@field utime user time
+@field stime system time
+@field cutime user time of children
+@field cstime system time of children
+@table times-table
+*/
+
+/*** Get process times.
+@treturn number return value
+@treturn times-table|errno Time data, or errno.
+@function times
+*/
 static int
 luxio_times(lua_State *L) /* 4.5.2 */
 {
@@ -598,12 +630,15 @@ luxio_times(lua_State *L) /* 4.5.2 */
 	return 2;
 }
 
-/**# Environment variables ****************************************************/
+/*** Environment variables.
+@section envvar
+*/
 
-/**% getenv
- *  retval = getenv(name);
- *  retval = getenv(name)
- */
+/*** Get an environment variable.
+@tparam string name
+@treturn string|nil return value
+@function getenv
+*/
 static int
 luxio_getenv(lua_State *L) /* 4.6.1 */
 {
@@ -619,10 +654,14 @@ luxio_getenv(lua_State *L) /* 4.6.1 */
 	return 1;
 }
 
-/**% setenv
- *  retval = setenv(name, value, overwrite);
- *  retval, errno = setenv(name, value[, overwrite/1])
- */
+/*** Set an environment variable.
+@tparam string name
+@tparam string value
+@tparam[opt=0] number overwrite
+@treturn number return value
+@treturn errno
+@function setenv
+*/
 static int
 luxio_setenv(lua_State *L) /* POSIX.1-2001 */
 {
@@ -636,10 +675,12 @@ luxio_setenv(lua_State *L) /* POSIX.1-2001 */
 	return 2;
 }
 
-/**% unsetenv
- *  retval = unsetenv(name);
- *  retval, errno = unsetenv(name)
- */
+/*** Unsets an environment variable.
+@tparam string name
+@treturn number return value
+@treturn errno
+@function unsetenv
+*/
 static int
 luxio_unsetenv(lua_State *L) /* POSIX.1-2001 */
 {
@@ -660,12 +701,11 @@ luxio_unsetenv(lua_State *L) /* POSIX.1-2001 */
 
 /* TODO: sysconf() 4.8.1 */
 
-/**# Directories *************************************************************/
-
-/**>
- * `readdir()` is a hideous API.  As such, we need to be reasonably high-level
- * here, otherwise everything is just too painful.
- */
+/*** Directories.
+readdir() is a hideous API.  As such, we need to be reasonably high-level here,
+otherwise everything is just too painful.
+@section dir
+*/
 
 #define LUXIO_READDIR_METATABLE "luxio.readdir"
 
@@ -714,11 +754,13 @@ luxio__bless_readdir(lua_State *L)
 
 	lua_setmetatable(L, -2);
 }
-/**% opendir
- * handle = opendir(path);
- * nil, errno = opendir(path)
- * handle, errno = opendir(path)
- */
+
+/*** Open a directory for enumeration.
+@tparam string dir directory to enumerate
+@treturn DIR|nil DIR object, or nil on error
+@treturn errno errno
+@function opendir
+*/
 static int
 luxio_opendir(lua_State *L) /* 5.1.2 */
 {
@@ -749,11 +791,12 @@ luxio_opendir(lua_State *L) /* 5.1.2 */
 	return 1;
 }
 
-/**% fdopendir
- * retval = fdopendir(fd);
- * nil, errno = fdopendir(fd)
- * handle, errno = fdopendir(fd)
- */
+/*** Open a directory for enumeration by open fd.
+@tparam number fd file descriptor
+@treturn DIR|nil DIR object, or nil on error
+@treturn errno errno
+@function fdopendir
+*/
 static int
 luxio_fdopendir(lua_State *L) /* POSIX.1-2008 */
 {
@@ -784,10 +827,10 @@ luxio_fdopendir(lua_State *L) /* POSIX.1-2008 */
 	return 1;
 }
 
-/**% closedir
- * closedir(handle);
- * closedir(handle)
- */
+/*** Close a previously open directory.
+@tparam DIR handle DIR object to close
+@function closedir
+*/
 static int
 luxio_closedir(lua_State *L) /* 5.1.2 */
 {
@@ -804,11 +847,20 @@ luxio_closedir(lua_State *L) /* 5.1.2 */
 	return 0;
 }
 
-/**% readdir
- * retval = readdir_r(handle, buf, ent);
- * nil, errno = readdir(handle) -- error _or_ end of directory
- * dirent, errno = readdir(handle) -- table with d_ino, d_name, and d_type
- */
+/*** readdir() information table.
+Returned by @{readdir}.  Some fields are OS-specific.
+@field d_ino inode number
+@field d_name file name
+@field d_type file type
+@table dirent
+*/
+
+/*** Read a directory entry
+@tparam DIR handle directory handle
+@treturn dirent|nil directory entry table, or nil on error
+@treturn errno errno
+@function readdir
+*/
 static int
 luxio_readdir(lua_State *L) /* 5.1.2 */
 {
@@ -843,10 +895,10 @@ luxio_readdir(lua_State *L) /* 5.1.2 */
 	return 1;
 }
 
-/**% rewinddir
- * rewinddir(handle);
- * rewinddir(handle)
- */
+/*** Reset directory stream
+@tparam DIR handle
+@function rewinddir
+*/
 static int
 luxio_rewinddir(lua_State *L) /* 5.1.2 */
 {