More documentation

1 files changed, 118 insertions, 50 deletions

diff --git a/luxio.c b/luxio.c
index 693fa0d..3832527 100644
--- a/luxio.c
+++ b/luxio.c
@@ -2074,8 +2074,10 @@ luxio_nanosleep(lua_State *L) /* 14.2.5 */
 	return 4;
 }
 
-/**# Message passing *********************************************************/
-
+/*** Message passing.
+POSIX message passing is not available on all platforms.
+@section msgpass
+*/
 #if defined(_POSIX_MESSAGE_PASSING)
 
 #include <mqueue.h>
@@ -2101,10 +2103,14 @@ luxio__mq_tostring(lua_State *L)
 	return 1;
 }
 
-/**% mq_open
- * retval = mq_open(name, oflag[, mode, attr]);
- * retval, errno = mq_open(name, oflag[, mode])
- */
+/*** Open a message queue.
+@tparam string name
+@tparam number oflag
+@tparam[opt] number mode
+@treturn mq|number message queue, or return value
+@treturn errno
+@function mq_open
+*/
 static int
 luxio_mq_open(lua_State *L) /* 15.2.1 */
 {
@@ -2147,10 +2153,12 @@ luxio_mq_open(lua_State *L) /* 15.2.1 */
 	return 2;
 }
 
-/**% mq_close
- * retval = mq_close(mq);
- * retval, errno = mq_close(mq)
- */
+/*** Close a message queue descriptor.
+@tparam mq mqdes
+@treturn number return value
+@treturn errno
+@function mq_close
+*/
 static int
 luxio_mq_close(lua_State *L) /* 15.2.2 */
 {
@@ -2162,10 +2170,12 @@ luxio_mq_close(lua_State *L) /* 15.2.2 */
 	return 2;
 }
 
-/**% mq_unlink
- * retval = mq_unlink(name);
- * retval, errno = mq_unlink(name)
- */
+/*** Remove a message queue.
+@tparam string name
+@treturn number return value
+@treturn errno
+@function mq_unlink
+*/
 static int
 luxio_mq_unlink(lua_State *L) /* 15.2.3 */
 {
@@ -2176,10 +2186,14 @@ luxio_mq_unlink(lua_State *L) /* 15.2.3 */
 	return 2;
 }
 
-/**% mq_send
- * retval = mq_send(mq, msg_ptr, msg_len, msg_prio);
- * retval, errno = mq_send(mq, string, prio)
- */
+/*** Send a message to a message queue.
+@tparam mq queue
+@tparam string message
+@tparam number priority
+@treturn number return value
+@treturn errno
+@function mq_send
+*/
 static int
 luxio_mq_send(lua_State *L) /* 15.2.4 */
 {
@@ -2194,10 +2208,15 @@ luxio_mq_send(lua_State *L) /* 15.2.4 */
 	return 2;
 }
 
-/**% mq_receive
- * retval = mq_receive(mq, msg_ptr, msg_ptr_sz, msg_prio);
- * retval, errno, msg, prio = mq_receive(mq)
- */
+
+/*** Receive a message from a message queue.
+@tparam mq queue
+@treturn number return value
+@treturn errno
+@treturn string|nil message data, or nil in case of error
+@treturn number|nil message priority, or nil in case of error
+@function mq_receive
+*/
 static int
 luxio_mq_receive(lua_State *L) /* 15.2.5 */
 {
@@ -2227,6 +2246,13 @@ luxio_mq_receive(lua_State *L) /* 15.2.5 */
 
 /* TODO: mq_notify() 15.2.6 */
 
+/*** Message queue attributes table.
+@field mq_flags 0 or O_NONBLOCK
+@field mq_maxmsg Maximum number of messages on queue
+@field mq_msgsize Maximum size of message (in bytes)
+@field mq_curmsgs Number of messages currently on queue
+@table mqattr-table
+*/
 static int
 luxio_make_attr_table(lua_State *L, struct mq_attr *attr)
 {
@@ -2248,10 +2274,15 @@ luxio_make_attr_table(lua_State *L, struct mq_attr *attr)
 	return 1;
 }
 
-/**% mq_setattr
- * retval = mq_setattr(mq, new, old);
- * retval, errno, old = mq_setattr(mq, flags)
- */
+/*** Set message queue attributes.
+As only the flags can be changed, this does not take a table.
+@tparam mq mqdes
+@tparam number flags
+@treturn number return value
+@treturn errno
+@treturn mqattr-table new attribute table
+@function mq_setattr
+*/
 static int
 luxio_mq_setattr(lua_State *L) /* 15.2.7 */
 {
@@ -2267,10 +2298,13 @@ luxio_mq_setattr(lua_State *L) /* 15.2.7 */
 	return 3;
 }
 
-/**% mq_getattr
- * retval = mq_getattr(mq, old);
- * retval, errno, old = mq_getattr(mq)
- */
+/*** Get message queue attributes.
+@tparam mq mqdes
+@treturn number return value
+@treturn errno
+@treturn mqattr-table current queue attributes
+@function mq_getattr
+*/
 static int
 luxio_mq_getattr(lua_State *L) /* 15.2.8 */
 {
@@ -2287,6 +2321,17 @@ luxio_mq_getattr(lua_State *L) /* 15.2.8 */
 
 #if _XOPEN_SOURCE >= 600 || _POSIX_C_SOURCE >= 200112L
 
+/*** Send a message to a queue, with a timeout.
+Not available on some systems.
+@tparam mq queue
+@tparam string message
+@tparam number priority
+@tparam number tv_sec
+@tparam number tv_nsec
+@treturn number return value
+@treturn errno
+@function mq_timedsend
+*/
 /**% mq_timedsend
  * retval = mq_timedsend(mq, msg, len, prio, timeout)
  * retval, errno = mq_timedsend(mq, msg, prio, tv_secs, tv_nsec)
@@ -2309,6 +2354,16 @@ luxio_mq_timedsend(lua_State *L) /* POSIX.1-2001 */
 	return 2;
 }
 
+/*** Receive a message from a message queue, with a timeout
+@tparam mq queue
+@treturn number return value
+@treturn errno
+@tparam number tv_sec
+@tparam number tv_nsec
+@treturn string|nil message data, or nil in case of error
+@treturn number|nil message priority, or nil in case of error
+@function mq_timedreceive
+*/
 /**% mq_timedreceive
  * retval = mq_timedsend(mq, bug, len, prio, timeout)
  * retval, errno, msg, prio = mq_timedreceive(mq, tv_secs, tv_nsec)
@@ -2350,19 +2405,18 @@ luxio_mq_timedreceive(lua_State *L) /* POSIX.1-2001 */
 
 /* Nope: use a threading library. */
 
-/**# Socket handling *********************************************************/
+/*** Socket handling.
+This interface is slightly cooked.  We provide userdata encapsulations for
+sockaddr and addrinfo types.  Use `getaddrinfo()` to obtain an addrinfo
+object, then use `ipairs()` over it to get each entry to try.
 
-/**>
- * This interface is slightly cooked.  We provide userdata encapsulations for
- * sockaddr and addrinfo types.  Use `getaddrinfo()` to obtain an addrinfo
- * object, then use `ipairs()` over it to get each entry to try.
- *
- * \t r, addrinfo = getaddrinfo("www.rjek.com", "80", 0, l.AF_UNSPEC, l.SOCK_STREAM)
- * \t for _, ai in ipairs(addrinfo) do
- * \t    sock = socket(ai.ai_family, ai.ai_socktype, ai.ai_protocol)
- * \t    if connect(sock, ai.ai_addr) >= 0 then break end
- * \t end
- */
+  r, addrinfo = getaddrinfo("www.rjek.com", "80", 0, l.AF_UNSPEC, l.SOCK_STREAM)
+  for _, ai in ipairs(addrinfo) do
+    sock = socket(ai.ai_family, ai.ai_socktype, ai.ai_protocol)
+    if connect(sock, ai.ai_addr) >= 0 then break end
+  end
+@section sock
+*/
 
 #define LUXIO_SOCKADDR_METATABLE_NAME "luxio.sockaddr"
 #ifndef UNIX_PATH_MAX
@@ -2542,6 +2596,14 @@ luxio_makesockaddr(lua_State *L)
  * retval = socket(domain, type, protocol);
  * retval, errno = socket(domain, type, protocol)
  */
+/*** Create an endpoint for communication.
+@tparam number domain
+@tparam number type
+@tparam number protocol
+@treturn number return value
+@treturn errno
+@function socket
+*/
 static int
 luxio_socket(lua_State *L)
 {
@@ -2555,10 +2617,13 @@ luxio_socket(lua_State *L)
 	return 2;
 }
 
-/**% listen
- * retval = listen(fd, backlog);
- * retval, errno = listen(fd, backlog)
- */
+/*** Listen for connections on a socket.
+@tparam number sockfd
+@tparam number backlog
+@treturn number return value
+@treturn errno
+@function listen
+*/
 static int
 luxio_listen(lua_State *L)
 {
@@ -2571,10 +2636,13 @@ luxio_listen(lua_State *L)
 	return 2;
 }
 
-/**% shutdown
- * retval = shutdown(fd, how);
- * retval, errno = shutdown(fd, how)
- */
+/*** Shut down part of a full-duplex connection.
+@tparam number sockfd
+@tparam number how
+@treturn number return value
+@treturn errno
+@function shutdown
+*/
 static int
 luxio_shutdown(lua_State *L)
 {