fixup! un-deprecate stream-like objects

Author: urkle

README.md

@@ -3168,7 +3168,7 @@ end
 
 Use `body false` to return `204 No Content` without any data or content-type.
 
-You can also set the response to a file with `file` and it will be streamed using Rack::Chunked.
+You can also set the response to a file with `file` and it will be streamed using `Rack::Chunked`.
 
 ```ruby
 class API < Grape::API
@@ -3178,8 +3178,8 @@ class API < Grape::API
 end
 ```
 
-If you want to stream non-file data you use the stream method and a Stream object.
-This is simply an object that responds to each and yields for each chunk to send to the client.
+If you want to stream non-file data you use the stream method and a `Stream` object.
+This is an object that responds to `each` and yields for each chunk to send to the client.
 Each chunk will be sent as it is yielded instead of waiting for all of the content to be available.
 
 ```ruby

UPGRADING.md

@@ -7,7 +7,7 @@ Upgrading Grape
 
 Previously in 0.16 stream-like objects were deprecated. This release restores their functionality for use-cases other than file streaming.
 
-For streaming files, simply use file always.
+For streaming files, use `file` always.
 
 ```ruby
 class API < Grape::API
@@ -17,22 +17,39 @@ class API < Grape::API
 end
 ```
 
-If you want to stream other kinds of content from a streamer object you may.
-An example would be a streamer class that fetches several pages of data from a database and streams the formatted responses back.
+Use `stream` to stream other kinds of content. In the following example a streamer class 
+streams paginated data from a database.
 
 ```ruby
-class MyObject
+class MyObject     
+  attr_accessor :result
+
+  def initialize(query)
+    @result = query
+  end
+  
   def each
     yield '['
-    # maybe do some paginated DB fetches and return each page
-    yield {}.to_json
+    # Do paginated DB fetches and return each page formatted
+    first = false
+    result.find_in_batches do |records|
+      yield process_records(records, first)
+      first = false
+    end
     yield ']'  
   end
+
+  def process_records(records, first)
+    buffer = +''
+    buffer << ',' unless first
+    buffer << records.map(&:to_json).join(',')
+    buffer
+  end
 end
 
 class API < Grape::API
   get '/' do
-    stream MyObject.new
+    stream MyObject.new(Sprocket.all)
   end
 end
 ```