doc: better "Rainbows!" RDoc examples and linkage

2 files changed, 12 insertions, 4 deletions

diff --git a/README b/README
index 3b0a4f1..c801efd 100644
--- a/README
+++ b/README
@@ -99,9 +99,12 @@ config file:
 
     Rainbows! do
       use :Revactor
-      worker_connections 128
+      worker_connections 400
     end
 
+See the {Rainbows! configuration documentation}[link:Rainbows.html#M000001]
+for more details.
+
 == Development
 
 * git: git://git.bogomips.org/rainbows.git
diff --git a/lib/rainbows.rb b/lib/rainbows.rb
index 4ba4b97..94246f5 100644
--- a/lib/rainbows.rb
+++ b/lib/rainbows.rb
@@ -17,18 +17,23 @@ module Rainbows
     end
   end
 
-  # configures Rainbows! with a given concurrency model to +use+ and
+  # configures \Rainbows! with a given concurrency model to +use+ and
   # a +worker_connections+ upper-bound.  This method may be called
   # inside a Unicorn/Rainbows configuration file:
   #
   #   Rainbows! do
   #     use :Revactor # this may also be :ThreadSpawn or :ThreadPool
-  #     worker_connections 128
+  #     worker_connections 400
   #   end
   #
+  #   # the rest of the Unicorn configuration
+  #   worker_processes 8
+  #
   # See the documentation for the respective Revactor, ThreadSpawn,
   # and ThreadPool classes for descriptions and recommendations for
-  # each of them.
+  # each of them.  The total number of clients we're able to serve is
+  # +worker_processes+ * +worker_connections+, so in the above example
+  # we can serve 8 * 400 = 3200 clients concurrently.
   def Rainbows!(&block)
     block_given? or raise ArgumentError, "Rainbows! requires a block"
     HttpServer.setup(block)