Start on documentation using ldoc

3 files changed, 151 insertions, 86 deletions

diff --git a/.bzrignore b/.bzrignore
index f010c02..0d1ab25 100644
--- a/.bzrignore
+++ b/.bzrignore
@@ -1,3 +1,5 @@
 luxio_constants.h
 luxio-5.1
 luxio-5.2
+doc/index.html
+doc/ldoc.css
diff --git a/config.ld b/config.ld
new file mode 100644
index 0000000..fb45794
--- /dev/null
+++ b/config.ld
@@ -0,0 +1,7 @@
+file = { "luxio.c" }
+format = "discount"
+project = "Luxio Light UNIX I/O"
+title = project
+dir = "doc"
+no_space_before_args = true
+
diff --git a/luxio.c b/luxio.c
index 3507464..0da3270 100644
--- a/luxio.c
+++ b/luxio.c
@@ -1,4 +1,4 @@
-/**!# Light Unix I/O for Lua
+/* Light Unix I/O for Lua
  * Copyright 2012 Rob Kendrick <rjek+luxio@rjek.com>
  *
  * Copyright 2012 Daniel Silverstone <dsilvers@digital-scurf.org>
@@ -6,6 +6,24 @@
  * Distributed under the same terms as Lua itself (MIT).
  */
 
+/***
+Low-level bindings to POSIX functionality.
+
+Luxio provides a very light-weight binding to many of the standard POSIX
+and common Unix library calls.  Where possible, calls are very raw.  In
+cases such as the `dirent` family, BSD sockets, the `getaddrinfo` family,
+and some other cases, they interfaces are somewhat "cooked" either to make
+them more efficient or even possible.
+
+For the simple raw uncooked functions, all we present here is an example
+of the C prototype, and possible styles for use in Lua.  You'll have to
+go looking in man pages for actual information on their use.
+
+Not all systems will provide all the functions described here.
+
+@module luxio
+*/
+ 
 #define LUXIO_RELEASE 6 /* clients use to check for features/bug fixes */
 #define LUXIO_ABI 0 /* clients use to check the ABI of calls is same */
 #define LUXIO_COPYRIGHT "Copyright 2013 Rob Kendrick <rjek+luxio@rjek.com>\n" \
@@ -57,28 +75,18 @@
 
 int luaopen_luxio(lua_State *L);
 
-/**# Introduction ************************************************************/
+/*** Process creation and execution.
+Functions to do with the creation of new processes and the execution of other
+programs.
+@section process
+*/
 
-/**>
- * Luxio provides a very light-weight binding to many of the standard POSIX
- * and common Unix library calls.  Where possible, calls are very raw.  In
- * cases such as the `dirent` family, BSD sockets, the `getaddrinfo` family,
- * and some other cases, they interfaces are somewhat "cooked" either to make
- * them more efficient or even possible.
- *
- * For the simple raw uncooked functions, all we present here is an example
- * of the C prototype, and possible styles for use in Lua.  You'll have to
- * go looking in man pages for actual information on their use.
- *
- * Not all systems will provide all the functions described here.
- */
+/*** Create a child process.
 
-/**# Process creation and execution ******************************************/
-
-/**% fork
- *  retval = fork();
- *  retval, errno = fork()
- */
+@treturn number return value
+@treturn errno errno
+@function fork
+*/
 static int
 luxio_fork(lua_State *L) /* 3.1.1 */
 {
@@ -122,20 +130,30 @@ luxio__exec(lua_State *L, bool usep)
 	return 2;
 }
 
-/**% exec
- *  retval = execv(path, argv[]);
- *  retval, errno = exec(path, ...)
- */
+/*** Execute a file.
+Calls execv().
+
+@tparam string path absolute path to executable
+@tparam string ... parameters to pass to executatable
+@treturn number return value
+@treturn errno errno
+@function exec
+*/
 static int
 luxio_exec(lua_State *L) /* 3.1.2 */
 {
 	return luxio__exec(L, false);
 }
 
-/**% execp
- *  retval = execvp(file, argv[]);
- *  retval, errno = execp(file, ...)
- */
+/*** Execute a file, searching PATH.
+Calls execp().
+
+@tparam string path name of executable
+@tparam string ... parameters to pass to executatable
+@treturn number return value
+@treturn number errno
+@function execp
+*/
 static int
 luxio_execp(lua_State *L) /* 3.1.2 */
 {
@@ -144,13 +162,19 @@ luxio_execp(lua_State *L) /* 3.1.2 */
 
 /* TODO: pthread_atfork() 3.1.3 */
 
-/**# Process termination */
+/*** Process termination.
+Functions to do with the termination of processes.
+@section termination
+*/
 
-/**% waitpid
- *  retval = waitpid(pid, *status, options);
- *  retval, status = waitpid(pid, options)
- *  retval, errno = waitpid(pid, options)
- */
+/*** Wait for a process to change state.
+
+@tparam number pid pid to wait on
+@tparam number options options for call
+@treturn number return value
+@treturn number|errno status code or errno if error
+@function waitpid
+*/
 static int
 luxio_waitpid(lua_State *L) /* 3.2.1 */
 {
@@ -176,28 +200,36 @@ luxio_waitpid(lua_State *L) /* 3.2.1 */
 		return 1;				      \
 	}
 
-/**% WIFEXITED
- *  retval = WIFEXITED(status);
- *  retval = WIFEXITED(status)
- */
+/*** Check status macro for WIFEXITED.
+@tparam number status code from `waitpid`()
+@treturn number true or false
+@function WIFEXITED
+*/
 WAITPID_STATUS(WIFEXITED)
 
 /**% WEXITSTATUS
  *  retval = WEXITSTATUS(status);
  *  retval = WIFEXITED(status)
  */
+/*** Obtain exit status code from child
+@tparam number status code from `waitpid`()
+@treturn number exit status code
+@function WEXITSTATUS
+*/
 WAITPID_STATUS(WEXITSTATUS)
 
-/**% WIFSIGNALED
- *  retval = WIFSIGNALED(status);
- *  retval = WIFSIGNALED(status)
- */
+/*** Check status macro for WIFSIGNALED.
+@tparam number status code from `waitpid`()
+@treturn number true or false
+@function WIFSIGNALLED
+*/
 WAITPID_STATUS(WIFSIGNALED)
 
-/**% WTERMSIG
- *  retval = WTERMSIG(status);
- *  retval = WTERMSIG(status);
- */
+/*** Obtain signal used to kill child.
+@tparam number status code from `waitpid`()
+@treturn number signal number
+@function WTERMSIG
+*/
 WAITPID_STATUS(WTERMSIG)
 
 #ifdef WCOREDUMP
@@ -205,35 +237,44 @@ WAITPID_STATUS(WTERMSIG)
  *  retval = WCOREDUMP(status);
  *  retval = WCOREDUMP(status)
  */
+/*** Check status macro for WCOREDUMP.
+@tparam number status code from `waitpid`()
+@treturn number true or false
+@function WCOREDUMP
+*/
 WAITPID_STATUS(WCOREDUMP)
 #endif
 
-/**% WIFSTOPPED
- *  retval = WIFSTOPPED(status);
- *  retval = WIFSTOPPED(status)
- */
+/*** Check status macro for WIFSTOPPED.
+@tparam number status code from `waitpid`()
+@treturn number true or false
+@function WIFSTOPPED
+*/
 WAITPID_STATUS(WIFSTOPPED)
 
-/**% WSTOPSIG
- *  retval = WSTOPSIG(status);
- *  retval = WSTOPSIG(status)
- */
+/*** Obtain signal number used to stop child.
+@tparam number status code from `waitpid`()
+@treturn number signal number
+@function WSTOPSIG
+*/
 WAITPID_STATUS(WSTOPSIG)
 
 #ifdef WIFCONTINUED
-/**% WIFCONTINUED
- *  retval = WIFCONTINUED(status);
- *  retval = WIFCONTINUED(status)
- */
+/*** Check status macro for WIFCONTINUED.
+Linux 2.6.10.
+@tparam number status code from `waitpid`()
+@treturn number true or false
+@function WIFCONTINUED
+*/
 WAITPID_STATUS(WIFCONTINUED)
 #endif
 
 #undef WAITPID_STATUS
 
-/**% _exit
- *  _exit(status);
- *  _exit(status)
- */
+/*** Terminate calling process.  Does not return.
+@tparam[opt=0] number exit status code.
+@function _exit
+*/
 static int
 luxio__exit(lua_State *L) /* 3.2.2 */
 {
@@ -244,12 +285,21 @@ luxio__exit(lua_State *L) /* 3.2.2 */
 	return 0;
 }
 
-/**# Signals *****************************************************************/
+/*** Signals.  Functions related to sending signals.
+@section signals
+*/
 
 /**% kill
  *  retval = kill(pid, sig);
  *  retval, errno = kill(pid, sig)
  */
+/*** Send signal to a process.
+@tparam number pid signal destination
+@tparam number signal signal to send
+@treturn number return value
+@treturn errno errno
+@function kill
+*/
 static int
 luxio_kill(lua_State *L) /* 3.3.2 */
 {
@@ -273,12 +323,15 @@ luxio_kill(lua_State *L) /* 3.3.2 */
 /* TODO: sigqueue() 3.3.9 */
 /* TODO: pthread_kill() 3.3.10 */
 
-/**# Timer operations ********************************************************/
+/*** Timer operations.
+@section timer
+*/
 
-/**% alarm
- *  retval = alarm(seconds);
- *  retval = alarm(seconds)
- */
+/*** Set an alarm clock for delivery of a signal.
+@tparam number seconds How long to wait before signal delivery
+@treturn number return value
+@function alarm
+*/
 static int
 luxio_alarm(lua_State *L) /* 3.4.1 */
 {
@@ -288,10 +341,10 @@ luxio_alarm(lua_State *L) /* 3.4.1 */
 	return 1;
 }
 
-/**% pause
- *  retval = pause();
- *  retval, errno = pause()
- */
+/*** Wait for a signal.
+@treturn number return value
+@function pause
+*/
 static int
 luxio_pause(lua_State *L) /* 3.4.2 */
 {
@@ -301,10 +354,11 @@ luxio_pause(lua_State *L) /* 3.4.2 */
 	return 2;
 }
 
-/**% sleep
- *  retval = sleep(seconds);
- *  retval = sleep(seconds)
- */
+/*** Sleep for the specified number of seconds.
+@tparam number seconds number of seconds to sleep
+@treturn number return value
+@function sleep
+*/
 static int
 luxio_sleep(lua_State *L) /* 3.4.3 */
 {
@@ -315,12 +369,14 @@ luxio_sleep(lua_State *L) /* 3.4.3 */
 	return 1;
 }
 
-/**# Process identification **************************************************/
+/*** Process identification
+@section procident
+*/
 
-/**% getpid
- *  retval = getpid();
- *  retval = getpid()
- */
+/*** Get process identification.
+@treturn number pid
+@function getpid
+*/
 static int
 luxio_getpid(lua_State *L) /* 4.1.1 */
 {
@@ -329,10 +385,10 @@ luxio_getpid(lua_State *L) /* 4.1.1 */
 	return 1;
 }
 
-/**% getppid
- *  retval = getppid();
- *  retval = getppid()
- */
+/*** Get process's parent's identification.
+@treturn number pid
+@function getppid
+*/
 static int
 luxio_getppid(lua_State *L) /* 4.1.1 */
 {