From 2aa3975d2cc9aac8467f40ceb561ba2346d2af5c Mon Sep 17 00:00:00 2001
From: Eric Wong <normalperson@yhbt.net>
Date: Sun, 13 Dec 2009 14:36:36 -0800
Subject: [PATCH] io: more RDoc

---
 lib/sunshowers/io.rb | 25 +++++++++++++++++--------
 1 file changed, 17 insertions(+), 8 deletions(-)

diff --git a/lib/sunshowers/io.rb b/lib/sunshowers/io.rb
index 5a95ef5..9db0621 100644
--- a/lib/sunshowers/io.rb
+++ b/lib/sunshowers/io.rb
@@ -44,7 +44,7 @@ module Sunshowers
       self
     end
 
-    # Retrieves the next record, returns nil if client close connection.
+    # Retrieves the next record, returns nil if client closes the connection.
     # The record may be either a UTF-8 or binary String, under
     # Ruby 1.9, the String encoding will be set appropriately.
     def gets
@@ -68,7 +68,9 @@ module Sunshowers
         raise ClientShutdown, e.message, []
     end
 
-    # writes a UTF-8 frame containing +buf+
+    # writes a UTF-8 frame containing +buf+.  We do not validate that
+    # +buf+ contains valid UTF-8, we assume you know what you are
+    # doing if you call this method directly.
     def write_utf8(buf)
       syswrite("\0#{binary(buf)}\xff")
     end
@@ -87,23 +89,31 @@ module Sunshowers
     end
 
     if ENC.nil?
-      def valid_utf8?(buf) # :nodoc:
-        buf.unpack("U*")
+      # :stopdoc:
+      U_STAR = "U*"
+      def valid_utf8?(buf)
+        buf.unpack(U_STAR)
         true
         rescue ArgumentError
           false
       end
 
-      def write(buf) # :nodoc:
+      def write(buf)
         valid_utf8?(buf) ? write_utf8(buf) : write_binary(buf)
       end
+      # :startdoc:
     else
-      def write(buf) # :nodoc:
+
+      # Writes out +buf+ as a Web Socket frame.  If +buf+ encoding is UTF-8,
+      # then it will be framed as UTF-8, otherwise it will be framed as
+      # binary with an explicit length set.
+      def write(buf)
         buf.encoding == ENC ? write_utf8(buf) : write_binary(buf)
       end
     end
 
-    def read(size = nil) # :nodoc:
+    # :stopdoc:
+    def read(size = nil)
       i = to_io
       # read with no args for Revactor compat
       i.respond_to?(:readpartial) ?
@@ -111,7 +121,6 @@ module Sunshowers
         i.read(size.nil? ? nil : size)
     end
 
-    # :stopdoc:
     if ENC.nil?
       def utf8!(buf)
         valid_utf8?(buf) or raise ProtocolError, "not UTF-8: #{buf.inspect}"
-- 
2.11.4.GIT