more rdoc documentation

lib/yajl.rb

@@ -47,15 +47,15 @@ def self.encode(obj, io, options={})
     end
   end
 
-  # Deprecated - See Yajl::Parser and Yajl::Encoder
+  # DEPRECATED - See Yajl::Parser and Yajl::Encoder
   module Stream
-    # Deprecated - See Yajl::Parser
+    # DEPRECATED - See Yajl::Parser
     def self.parse(io)
       STDERR.puts "WARNING: Yajl::Stream has be deprecated and will most likely be gone in the next release. Use the Yajl::Parser class instead."
       Parser.new.parse(io)
     end
 
-    # Deprecated - See Yajl::Encoder
+    # DEPRECATED - See Yajl::Encoder
     def self.encode(obj, io)
       STDERR.puts "WARNING: Yajl::Stream has be deprecated and will most likely be gone in the next release. Use the Yajl::Encoder class instead."
       Encoder.new.encode(obj, io)

lib/yajl/bzip2/stream_reader.rb

@@ -1,11 +1,11 @@
 # encoding: UTF-8
 module Yajl
   module Bzip2
-    # === Yajl::Bzip2::StreamReader
-    #
     # This is a wrapper around Bzip::Reader to allow it's #read method to adhere
     # to the IO spec, allowing for two parameters (length, and buffer)
     class StreamReader < ::Bzip2::Reader
+
+      # A helper method to allow use similar to IO#read
       def read(len=nil, buffer=nil)
         unless buffer.nil?
           buffer.replace super(len)
@@ -14,8 +14,11 @@ def read(len=nil, buffer=nil)
         super(len)
       end
 
-      def self.parse(io)
-        Yajl::Parser.new.parse(new(io))
+      # Helper method for one-off parsing from a bzip2-compressed stream
+      #
+      # See Yajl::Parser#parse for parameter documentation
+      def self.parse(io, options={}, buffer_size=nil, &block)
+        Yajl::Parser.new(options).parse(new(io, buffer_size, &block))
       end
     end
   end

lib/yajl/bzip2/stream_writer.rb

@@ -1,8 +1,12 @@
 # encoding: UTF-8
 module Yajl
   module Bzip2
-    # === Yajl::Bzip2::StreamWriter
+    # A wrapper around the Bzip2::Writer class for easier JSON stream encoding
     class StreamWriter < ::Bzip2::Writer
+
+      # A helper method for encoding to a bzip2-compressed stream
+      #
+      # Look up Yajl::Encoder#encode for parameter documentation
       def self.encode(obj, io)
         Yajl::Encoder.new.encode(obj, new(io))
       end

lib/yajl/deflate/stream_reader.rb

@@ -1,25 +1,28 @@
 # encoding: UTF-8
 module Yajl
   module Deflate
-    # === Yajl::Deflate::StreamReader
-    #
     # This is a wrapper around Zlib::Inflate, creating a #read method that adheres
     # to the IO spec, allowing for two parameters (length, and buffer)
     class StreamReader < ::Zlib::Inflate
+
+      # Wrapper to the initialize method so we can set the initial IO to parse from.
       def initialize(io, options)
         @io = io
         super(options)
       end
 
+      # A helper method to allow use similar to IO#read
       def read(len=nil, buffer=nil)
         buffer.replace inflate(@io.read(len)) and return unless buffer.nil?
         inflate(@io.read(len))
       end
-
       alias :eof? :finished?
 
-      def self.parse(io, options=nil)
-        Yajl::Parser.new.parse(new(io, options))
+      # Helper method for one-off parsing from a deflate-compressed stream
+      #
+      # See Yajl::Parser#parse for parameter documentation
+      def self.parse(io, options={}, buffer_size=nil, &block)
+        Yajl::Parser.new(options).parse(new(io, buffer_size, &block))
       end
     end
   end

lib/yajl/deflate/stream_writer.rb

@@ -1,13 +1,18 @@
 # encoding: UTF-8
 module Yajl
   module Deflate
-    # === Yajl::Deflate::StreamWriter
+    # A wrapper around the Zlib::Deflate class for easier JSON stream parsing
     class StreamWriter < ::Zlib::Deflate
+
+      # A helper method to allow use similar to IO#write
       def write(str)
         deflate(str)
         str.size unless str.nil?
       end
 
+      # A helper method for one-off encoding to a deflate-compressed stream
+      #
+      # Look up Yajl::Encoder#encode for parameter documentation
       def self.encode(obj, io)
         Yajl::Encoder.new.encode(obj, new(io))
       end

lib/yajl/gzip/stream_reader.rb

@@ -1,11 +1,11 @@
 # encoding: UTF-8
 module Yajl
   module Gzip
-    # === Yajl::GzipStreamReader
-    #
     # This is a wrapper around Zlib::GzipReader to allow it's #read method to adhere
     # to the IO spec, allowing for two parameters (length, and buffer)
     class StreamReader < ::Zlib::GzipReader
+
+      # Wrapper method to allow use similar to IO#read
       def read(len=nil, buffer=nil)
         unless buffer.nil?
           buffer.replace super(len)
@@ -14,8 +14,11 @@ def read(len=nil, buffer=nil)
         super(len)
       end
 
-      def self.parse(io)
-        Yajl::Parser.new.parse(new(io))
+      # Helper method for one-off parsing from a gzip-compressed stream
+      #
+      # See Yajl::Parser#parse for parameter documentation
+      def self.parse(io, options={}, buffer_size=nil, &block)
+        Yajl::Parser.new(options).parse(new(io, buffer_size, &block))
       end
     end
   end

lib/yajl/gzip/stream_writer.rb

@@ -1,8 +1,11 @@
 # encoding: UTF-8
 module Yajl
   module Gzip
-    # === Yajl::Gzip::StreamWriter
+    # Wraper around the Zlib::GzipWriter class
     class StreamWriter < ::Zlib::GzipWriter
+      # A helper method for one-off encoding to a gzip-compressed stream
+      #
+      # Look up Yajl::Encoder#encode for parameter documentation
       def self.encode(obj, io)
         Yajl::Encoder.new.encode(obj, new(io))
       end

lib/yajl/http_stream.rb

@@ -3,13 +3,10 @@
 require 'yajl' unless defined?(Yajl::Parser)
 
 module Yajl
-  # == Yajl::HttpStream
-  #
   # This module is for making HTTP requests to which the response bodies (and possibly requests in the near future)
   # are streamed directly into Yajl.
   class HttpStream
-    # === Yajl::HttpStream::InvalidContentType
-    #
+
     # This Exception is thrown when an HTTP response isn't application/json
     # and therefore cannot be parsed.
     class InvalidContentType < Exception; end
@@ -22,8 +19,7 @@ class InvalidContentType < Exception; end
     # 1. a raw socket is opened to the server/host provided
     # 2. the request is made using HTTP/1.0, Accept-encoding: gzip (deflate support coming soon, too)
     # 3. the response is read until the end of the headers
-    # 4. the _socket itself_ is passed directly to Yajl, for direct parsing off the stream;
-    #    As it's being received over the wire!
+    # 4. the _socket itself_ is passed directly to Yajl, for direct parsing off the stream; As it's being received over the wire!
     def self.get(uri, opts = {}, &block)
       user_agent = opts.has_key?(['User-Agent']) ? opts['User-Agent'] : "Yajl::HttpStream #{Yajl::VERSION}"
 

spec/encoding/encoding_spec.rb

@@ -72,6 +72,10 @@
       encoder.encode(obj, io)
     end
     io.rewind
-    io.read.should == "{\"foo\":\"bar\",\"baz\":1234}\n{\"foo\":\"bar\",\"baz\":1234}\n{\"foo\":\"bar\",\"baz\":1234}\n{\"foo\":\"bar\",\"baz\":1234}\n{\"foo\":\"bar\",\"baz\":1234}\n"
+    output = "{\"baz\":1234,\"foo\":\"bar\"}\n{\"baz\":1234,\"foo\":\"bar\"}\n{\"baz\":1234,\"foo\":\"bar\"}\n{\"baz\":1234,\"foo\":\"bar\"}\n{\"baz\":1234,\"foo\":\"bar\"}\n"
+    if RUBY_VERSION.include?('1.9') # FIXME
+      output = "{\"foo\":\"bar\",\"baz\":1234}\n{\"foo\":\"bar\",\"baz\":1234}\n{\"foo\":\"bar\",\"baz\":1234}\n{\"foo\":\"bar\",\"baz\":1234}\n{\"foo\":\"bar\",\"baz\":1234}\n"
+    end
+    io.read.should == output
   end
 end