kcar/response: rdoc public methods

1 files changed, 31 insertions, 10 deletions

diff --git a/lib/kcar/response.rb b/lib/kcar/response.rb
index 724e1df..ef93f12 100644
--- a/lib/kcar/response.rb
+++ b/lib/kcar/response.rb
@@ -1,16 +1,31 @@
 # -*- encoding: binary -*-
 
 module Kcar
+
+# This may be used to generate a Rack response
+#
 class Response < Struct.new(:sock, :unchunk, :hdr, :buf, :parser)
 
+  # :stopdoc:
   LAST_CHUNK = "0\r\n"
   CRLF = "\r\n"
+  # :startdoc:
+
+  # By default we readpartial at most 16K off a socket at once
   READ_SIZE = 0x4000
 
+  # initializes a socket, +sock+ must respond to the "readpartial"
+  # method.  +unchunk+ may be set to disable transparent unchunking
+  # +hdr+ may be a Hash, Array, or Rack::Utils::HeaderHash
   def initialize(sock, unchunk = true, hdr = {})
     super(sock, unchunk, hdr, "", Parser.new)
   end
 
+  # returns a 3-element array suitable for use as a Rack response:
+  #    [ status, headers, body ]
+  #
+  # this method will not return until the response headers are fully parsed,
+  # but the body returned will be this Kcar::Response handler itself.
   def read
     buf << sock.readpartial(READ_SIZE) if buf.empty?
     while (response = parser.headers(hdr, buf)).nil?
@@ -19,12 +34,16 @@ class Response < Struct.new(:sock, :unchunk, :hdr, :buf, :parser)
     response << self
   end
 
-  def reset
-    parser.reset
-    hdr.clear
+  # this is expected to be called by our Rack server, it will close
+  # our given +sock+ object if keepalive is not used otherwise it
+  # will just reset the parser and clear the header object
+  def close
+    parser.keepalive? ? reset : sock.close
   end
 
-  # this method allows Kcar::Session to be used as a Rack response body
+  # this method allows our Kcar::Response object to be used as a Rack response
+  # body.  It may only be called once (usually by a Rack server) as it streams
+  # the response body off the our socket object.
   def each(&block)
     return if parser.body_eof?
     if unchunk
@@ -39,6 +58,12 @@ class Response < Struct.new(:sock, :unchunk, :hdr, :buf, :parser)
     rescue EOFError
   end
 
+  # :stopdoc:
+  def reset
+    parser.reset
+    hdr.clear
+  end
+
   def each_rechunk(&block)
     # We have to filter_body to keep track of parser state
     # (which sucks).  Also, as a benefit to clients we'll rechunk
@@ -70,11 +95,6 @@ class Response < Struct.new(:sock, :unchunk, :hdr, :buf, :parser)
     end
   end
 
-  # this is called by our Rack server
-  def close
-    parser.keepalive? ? reset : sock.close
-  end
-
   def each_until_eof(&block)
     yield buf unless buf.empty?
     # easy, just read and write everything until EOFError
@@ -125,6 +145,7 @@ class Response < Struct.new(:sock, :unchunk, :hdr, :buf, :parser)
       buf << sock.readpartial(READ_SIZE, dst)
     end
   end
+  # :startdoc:
 
-end # class Session
+end # class Response
 end # module Kcar