doc: fully RDoc all methods and classes

Whee!

5 files changed, 74 insertions, 1 deletions

diff --git a/.document b/.document
index c6c1568..ebb8397 100644
--- a/.document
+++ b/.document
@@ -8,8 +8,9 @@ ISSUES
 HACKING
 lib
 ext/kgio/accept.c
+ext/kgio/autopush.c
 ext/kgio/connect.c
 ext/kgio/kgio_ext.c
+ext/kgio/poll.c
 ext/kgio/read_write.c
 ext/kgio/wait.c
-ext/kgio/poll.c
diff --git a/ext/kgio/accept.c b/ext/kgio/accept.c
index 479a606..902145c 100644
--- a/ext/kgio/accept.c
+++ b/ext/kgio/accept.c
@@ -453,13 +453,26 @@ void init_kgio_accept(void)
         rb_define_singleton_method(mKgio, "accept_class=", set_accepted, 1);
         rb_define_singleton_method(mKgio, "accept_class", get_accepted, 0);
 
+        /*
+         * Document-class: Kgio::UNIXServer
+         *
+         * Kgio::UNIXServer should be used in place of the plain UNIXServer
+         * when kgio_accept and kgio_tryaccept methods are needed.
+         */
         cUNIXServer = rb_const_get(rb_cObject, rb_intern("UNIXServer"));
         cUNIXServer = rb_define_class_under(mKgio, "UNIXServer", cUNIXServer);
         rb_define_method(cUNIXServer, "kgio_tryaccept", unix_tryaccept, -1);
         rb_define_method(cUNIXServer, "kgio_accept", unix_accept, -1);
 
+        /*
+         * Document-class: Kgio::TCPServer
+         *
+         * Kgio::TCPServer should be used in place of the plain TCPServer
+         * when kgio_accept and kgio_tryaccept methods are needed.
+         */
         cTCPServer = rb_const_get(rb_cObject, rb_intern("TCPServer"));
         cTCPServer = rb_define_class_under(mKgio, "TCPServer", cTCPServer);
+
         rb_define_method(cTCPServer, "kgio_tryaccept", tcp_tryaccept, -1);
         rb_define_method(cTCPServer, "kgio_accept", tcp_accept, -1);
         init_sock_for_fd();
diff --git a/ext/kgio/autopush.c b/ext/kgio/autopush.c
index 058e202..eface66 100644
--- a/ext/kgio/autopush.c
+++ b/ext/kgio/autopush.c
@@ -78,11 +78,32 @@ static void state_set(VALUE io, enum autopush_state state)
 static enum autopush_state detect_acceptor_state(VALUE io);
 static void push_pending_data(VALUE io);
 
+/*
+ * call-seq:
+ *        Kgio.autopush? -> true or false
+ *
+ * Returns whether or not autopush is enabled.
+ *
+ * Only available on systems with TCP_CORK (Linux) or
+ * TCP_NOPUSH (FreeBSD, and maybe other *BSDs).
+ */
 static VALUE s_get_autopush(VALUE self)
 {
         return enabled ? Qtrue : Qfalse;
 }
 
+/*
+ * call-seq:
+ *        Kgio.autopush = true
+ *        Kgio.autopush = false
+ *
+ * Enables or disables autopush for sockets created with kgio_accept
+ * and kgio_tryaccept methods.  Autopush relies on TCP_CORK/TCP_NOPUSH
+ * being enabled on the listen socket.
+ *
+ * Only available on systems with TCP_CORK (Linux) or
+ * TCP_NOPUSH (FreeBSD, and maybe other *BSDs).
+ */
 static VALUE s_set_autopush(VALUE self, VALUE val)
 {
         enabled = RTEST(val);
@@ -90,11 +111,35 @@ static VALUE s_set_autopush(VALUE self, VALUE val)
         return val;
 }
 
+/*
+ * call-seq:
+ *
+ *        io.kgio_autopush?  -> true or false
+ *
+ * Returns the current autopush state of the Kgio::SocketMethods-enabled
+ * socket.
+ *
+ * Only available on systems with TCP_CORK (Linux) or
+ * TCP_NOPUSH (FreeBSD, and maybe other *BSDs).
+ */
 static VALUE autopush_get(VALUE io)
 {
         return state_get(io) <= 0 ? Qfalse : Qtrue;
 }
 
+/*
+ * call-seq:
+ *
+ *        io.kgio_autopush = true
+ *        io.kgio_autopush = false
+ *
+ * Enables or disables autopush on any given Kgio::SocketMethods-capable
+ * IO object.  This does NOT enable or disable TCP_NOPUSH/TCP_CORK right
+ * away, that must be done with IO.setsockopt
+ *
+ * Only available on systems with TCP_CORK (Linux) or
+ * TCP_NOPUSH (FreeBSD, and maybe other *BSDs).
+ */
 static VALUE autopush_set(VALUE io, VALUE vbool)
 {
         int fd = my_fileno(io);
diff --git a/ext/kgio/connect.c b/ext/kgio/connect.c
index 0c8a9b2..1545853 100644
--- a/ext/kgio/connect.c
+++ b/ext/kgio/connect.c
@@ -257,12 +257,24 @@ void init_kgio_connect(void)
         rb_define_singleton_method(cKgio_Socket, "new", kgio_connect, 1);
         rb_define_singleton_method(cKgio_Socket, "start", kgio_start, 1);
 
+        /*
+         * Document-class: Kgio::TCPSocket
+         *
+         * Kgio::TCPSocket should be used in place of the plain TCPSocket
+         * when kgio_* methods are needed.
+         */
         cTCPSocket = rb_const_get(rb_cObject, rb_intern("TCPSocket"));
         cTCPSocket = rb_define_class_under(mKgio, "TCPSocket", cTCPSocket);
         rb_include_module(cTCPSocket, mSocketMethods);
         rb_define_singleton_method(cTCPSocket, "new", kgio_tcp_connect, 2);
         rb_define_singleton_method(cTCPSocket, "start", kgio_tcp_start, 2);
 
+        /*
+         * Document-class: Kgio::UNIXSocket
+         *
+         * Kgio::UNIXSocket should be used in place of the plain UNIXSocket
+         * when kgio_* methods are needed.
+         */
         cUNIXSocket = rb_const_get(rb_cObject, rb_intern("UNIXSocket"));
         cUNIXSocket = rb_define_class_under(mKgio, "UNIXSocket", cUNIXSocket);
         rb_include_module(cUNIXSocket, mSocketMethods);
diff --git a/lib/kgio.rb b/lib/kgio.rb
index 0d28d4e..5de431b 100644
--- a/lib/kgio.rb
+++ b/lib/kgio.rb
@@ -1,5 +1,7 @@
 # -*- encoding: binary -*-
 require 'socket'
+
+# See the {README}[link:index.html]
 module Kgio
 
   # The IPv4 address of UNIX domain sockets, useful for creating