doc: misc cleanups and additions for RDoc

This is also our website, so we need to document the new
Cool.io-based concurrency options for users and point
existing Rev* users to it.

14 files changed, 93 insertions, 11 deletions

diff --git a/Documentation/comparison.haml b/Documentation/comparison.haml
index 2461234..5801782 100644
--- a/Documentation/comparison.haml
+++ b/Documentation/comparison.haml
@@ -120,9 +120,10 @@
     %td.slow no
 %ul
   %li
-    RevThread* + 1.8 requires Rev >= 0.3.2 for reasonable performance
+    All Rev-based options can also use "Coolio" instead.  Cool.io should
+    also work with Rubinius (though we haven't had time to test).
   %li
-    waiting on Rubinius for better signal handling
+    CoolioThread* and RevThread* requires Ruby 1.9 reasonable performance
   %li
     rack.input streaming is what makes
     %a(href="http://upr.bogomips.org/") upload progress,
diff --git a/lib/rainbows/coolio.rb b/lib/rainbows/coolio.rb
index fb0a305..2fdc741 100644
--- a/lib/rainbows/coolio.rb
+++ b/lib/rainbows/coolio.rb
@@ -1,2 +1,23 @@
-# :enddoc:
+# -*- encoding: binary -*-
+# :stopdoc:
 Rainbows.const_set(:Coolio, Rainbows::Rev)
+# :startdoc:
+
+# Implements a basic single-threaded event model with
+# {Cool.io}[http://coolio.github.com/].  It is capable of handling
+# thousands of simultaneous client connections, but with only a
+# single-threaded app dispatch.  It is suited for slow clients and
+# fast applications (applications that do not have slow network
+# dependencies) or applications that use DevFdResponse for deferrable
+# response bodies.  It does not require your Rack application to be
+# thread-safe, reentrancy is only required for the DevFdResponse body
+# generator.
+#
+# Compatibility: Whatever Cool.io itself supports, currently Ruby
+# 1.8/1.9.
+#
+# This model does not implement as streaming "rack.input" which
+# allows the Rack application to process data as it arrives.  This
+# means "rack.input" will be fully buffered in memory or to a
+# temporary file before the application is entered.
+module Rainbows::Coolio; end
diff --git a/lib/rainbows/coolio_fiber_spawn.rb b/lib/rainbows/coolio_fiber_spawn.rb
index 272d111..6e573b4 100644
--- a/lib/rainbows/coolio_fiber_spawn.rb
+++ b/lib/rainbows/coolio_fiber_spawn.rb
@@ -1,2 +1,13 @@
-# :enddoc:
+# -*- encoding: binary -*-
+# :stopdoc:
 Rainbows.const_set(:CoolioFiberSpawn, Rainbows::RevFiberSpawn)
+# :startdoc:
+
+# A combination of the Coolio and FiberSpawn models.  This allows Ruby
+# 1.9 Fiber-based concurrency for application processing while
+# exposing a synchronous execution model and using scalable network
+# concurrency provided by Cool.io.  A "rack.input" is exposed as well
+# being Sunshowers-compatible.  Applications are strongly advised to
+# wrap all slow IO objects (sockets, pipes) using the
+# Rainbows::Fiber::IO or a Cool.io-compatible class whenever possible.
+module Rainbows::CoolFiberSpawn; end
diff --git a/lib/rainbows/coolio_thread_pool.rb b/lib/rainbows/coolio_thread_pool.rb
index acb1bdb..f96795e 100644
--- a/lib/rainbows/coolio_thread_pool.rb
+++ b/lib/rainbows/coolio_thread_pool.rb
@@ -1,2 +1,20 @@
-# :enddoc:
+# -*- encoding: binary -*-
+# :stopdoc:
 Rainbows.const_set(:CoolioThreadPool, Rainbows::RevThreadSpawn)
+# :startdoc:
+
+# A combination of the Coolio and ThreadPool models.  This allows Ruby
+# Thread-based concurrency for application processing.  It DOES NOT
+# expose a streamable "rack.input" for upload processing within the
+# app.  DevFdResponse should be used with this class to proxy
+# asynchronous responses.  All network I/O between the client and
+# server are handled by the main thread and outside of the core
+# application dispatch.
+#
+# Unlike ThreadPool, Cool.io makes this model highly suitable for
+# slow clients and applications with medium-to-slow response times
+# (I/O bound), but less suitable for sleepy applications.
+#
+# This concurrency model is designed for Ruby 1.9, and Ruby 1.8
+# users are NOT advised to use this due to high CPU usage.
+module Rainbows::CoolThreadPool; end
diff --git a/lib/rainbows/coolio_thread_spawn.rb b/lib/rainbows/coolio_thread_spawn.rb
index 1ca5c6c..81591d9 100644
--- a/lib/rainbows/coolio_thread_spawn.rb
+++ b/lib/rainbows/coolio_thread_spawn.rb
@@ -1,2 +1,20 @@
-# :enddoc:
+# -*- encoding: binary -*-
+# :stopdoc:
 Rainbows.const_set(:CoolioThreadSpawn, Rainbows::RevThreadSpawn)
+# :startdoc:
+
+# A combination of the Coolio and ThreadSpawn models.  This allows Ruby
+# Thread-based concurrency for application processing.  It DOES NOT
+# expose a streamable "rack.input" for upload processing within the
+# app.  DevFdResponse should be used with this class to proxy
+# asynchronous responses.  All network I/O between the client and
+# server are handled by the main thread and outside of the core
+# application dispatch.
+#
+# Unlike ThreadSpawn, Cool.io makes this model highly suitable for
+# slow clients and applications with medium-to-slow response times
+# (I/O bound), but less suitable for sleepy applications.
+#
+# This concurrency model is designed for Ruby 1.9, and Ruby 1.8
+# users are NOT advised to use this due to high CPU usage.
+module Rainbows::CoolioThreadSpawn; end
diff --git a/lib/rainbows/fiber.rb b/lib/rainbows/fiber.rb
index ed01147..3dc97c3 100644
--- a/lib/rainbows/fiber.rb
+++ b/lib/rainbows/fiber.rb
@@ -1,14 +1,16 @@
 # -*- encoding: binary -*-
-# :enddoc:
+# :stopdoc:
 begin
   require 'fiber'
 rescue LoadError
   defined?(NeverBlock) or raise
 end
+# :startdoc:
 
-# core module for all things that use Fibers in Rainbows!
+# core namespace for all things that use Fibers in \Rainbows!
 module Rainbows::Fiber
 
+  # :stopdoc:
   # blocked readers (key: fileno, value: Rainbows::Fiber::IO object)
   RD = []
 
@@ -17,6 +19,7 @@ module Rainbows::Fiber
 
   # sleeping fibers go here (key: Fiber object, value: wakeup time)
   ZZ = {}
+  # :startdoc:
 
   # puts the current Fiber into uninterruptible sleep for at least
   # +seconds+.  Unlike Kernel#sleep, this it is not possible to sleep
diff --git a/lib/rainbows/fiber/io.rb b/lib/rainbows/fiber/io.rb
index 6c3d91c..ac243a4 100644
--- a/lib/rainbows/fiber/io.rb
+++ b/lib/rainbows/fiber/io.rb
@@ -18,7 +18,7 @@ class Rainbows::Fiber::IO
   end
   # :startdoc:
 
-  # needed to write errors with
+  # no longer used internally within Rainbows!, only for compatibility
   def write_nonblock(buf)
     @to_io.write_nonblock(buf)
   end
diff --git a/lib/rainbows/rev.rb b/lib/rainbows/rev.rb
index cb4701b..1e425fe 100644
--- a/lib/rainbows/rev.rb
+++ b/lib/rainbows/rev.rb
@@ -8,6 +8,8 @@ rescue LoadError
 end
 require 'rev' if defined?(Coolio)
 
+# Coolio is the new version of this, use that instead.
+#
 # Implements a basic single-threaded event model with
 # {Rev}[http://rev.rubyforge.org/].  It is capable of handling
 # thousands of simultaneous client connections, but with only a
diff --git a/lib/rainbows/rev_fiber_spawn.rb b/lib/rainbows/rev_fiber_spawn.rb
index 39483b3..4338703 100644
--- a/lib/rainbows/rev_fiber_spawn.rb
+++ b/lib/rainbows/rev_fiber_spawn.rb
@@ -1,6 +1,8 @@
 # -*- encoding: binary -*-
 require 'rainbows/fiber/rev'
 
+# CoolioFiberSpawn is the new version of this, use that instead.
+#
 # A combination of the Rev and FiberSpawn models.  This allows Ruby
 # 1.9 Fiber-based concurrency for application processing while
 # exposing a synchronous execution model and using scalable network
diff --git a/lib/rainbows/rev_thread_pool.rb b/lib/rainbows/rev_thread_pool.rb
index b377062..4366086 100644
--- a/lib/rainbows/rev_thread_pool.rb
+++ b/lib/rainbows/rev_thread_pool.rb
@@ -1,5 +1,7 @@
 # -*- encoding: binary -*-
 
+# CoolioThreadPool is the new version of this, use that instead.
+#
 # A combination of the Rev and ThreadPool models.  This allows Ruby
 # Thread-based concurrency for application processing.  It DOES NOT
 # expose a streamable "rack.input" for upload processing within the
diff --git a/lib/rainbows/rev_thread_spawn.rb b/lib/rainbows/rev_thread_spawn.rb
index 94e9503..f19b68f 100644
--- a/lib/rainbows/rev_thread_spawn.rb
+++ b/lib/rainbows/rev_thread_spawn.rb
@@ -1,5 +1,7 @@
 # -*- encoding: binary -*-
 
+# CoolioThreadPool is the new version of this, use that instead.
+#
 # A combination of the Rev and ThreadSpawn models.  This allows Ruby
 # Thread-based concurrency for application processing.  It DOES NOT
 # expose a streamable "rack.input" for upload processing within the
diff --git a/lib/rainbows/worker_yield.rb b/lib/rainbows/worker_yield.rb
index ec2a289..e81d358 100644
--- a/lib/rainbows/worker_yield.rb
+++ b/lib/rainbows/worker_yield.rb
@@ -1,3 +1,4 @@
+# -*- encoding: binary -*-
 # :enddoc:
 module Rainbows::WorkerYield
 
diff --git a/lib/rainbows/writer_thread_pool/client.rb b/lib/rainbows/writer_thread_pool/client.rb
index 5889e84..3cc3335 100644
--- a/lib/rainbows/writer_thread_pool/client.rb
+++ b/lib/rainbows/writer_thread_pool/client.rb
@@ -1,8 +1,8 @@
 # -*- encoding: binary -*-
-#
+# :enddoc:
 # used to wrap a BasicSocket to use with +q+ for all writes
 # this is compatible with IO.select
-class Rainbows::WriterThreadPool::Client < Struct.new(:to_io, :q) # :nodoc:
+class Rainbows::WriterThreadPool::Client < Struct.new(:to_io, :q)
   include Rainbows::SocketProxy
 
   def write(buf)
diff --git a/lib/rainbows/writer_thread_spawn/client.rb b/lib/rainbows/writer_thread_spawn/client.rb
index ed60f42..8f65c19 100644
--- a/lib/rainbows/writer_thread_spawn/client.rb
+++ b/lib/rainbows/writer_thread_spawn/client.rb
@@ -1,4 +1,5 @@
 # -*- encoding: binary -*-
+# :enddoc:
 # used to wrap a BasicSocket to use with +q+ for all writes
 # this is compatible with IO.select
 class Rainbows::WriterThreadSpawn::Client < Struct.new(:to_io, :q, :thr)