More docs, docgen now expands \t

1 files changed, 30 insertions, 1 deletions

diff --git a/luxio.c b/luxio.c
index ef32bba..efffb11 100644
--- a/luxio.c
+++ b/luxio.c
@@ -1951,6 +1951,18 @@ luxio_mq_timedreceive(lua_State *L) /* POSIX.1-2001 */
 
 /**# 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.
+ *
+ * \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
+ */
+
 #define LUXIO_SOCKADDR_METATABLE_NAME "luxio.sockaddr"
 #ifndef UNIX_PATH_MAX
 /* From man 7 unix */
@@ -2311,6 +2323,10 @@ luxio_getsockopt(lua_State *L)
 	return luaL_error(L, "unhandled socket level %d", level);
 }
 
+/**% setsockopt
+ * retval = setsockopt(fd, level, optname, optval, optlen);
+ * retval, errno = setsockopt(fd, level, optname, optval)
+ */
 static int
 luxio_setsockopt(lua_State *L)
 {
@@ -2374,6 +2390,10 @@ luxio_setsockopt(lua_State *L)
 	return luaL_error(L, "unhandled socket level %d", level);
 }
 
+/**% gai_strerror
+ * retval = gai_strerror(errnum);
+ * retval = gai_strerror(errno)
+ */
 static int
 luxio_gai_strerror(lua_State *L)
 {
@@ -2382,6 +2402,11 @@ luxio_gai_strerror(lua_State *L)
 	return 1;
 }
 
+/**% getaddrinfo
+ * retval = getaddrinfo(node, service, hints, res);
+ * errcode = getaddrinfo(node, service[, ai_flags/0, ai_family/AF_UNSPEC, ai_socktype/0, ai_protocol/0])
+ * addrinfo = getaddrinfo(node, service[, ai_flags/0, ai_family/AF_UNSPEC, ai_socktype/0, ai_protocol/0])
+ */
 static int
 luxio_getaddrinfo(lua_State *L)
 {
@@ -2846,8 +2871,12 @@ luxio_gettimeofday(lua_State *L)
 	return 1;
 }
 
-/* Misc utility functions ****************************************************/
+/**# Misc utility functions **************************************************/
 
+/**% strerror
+ * retval = strerror(errno);
+ * retval = strerror(errno)
+ */
 static int
 luxio_strerror(lua_State *L)
 {