Improve documentation for ActionController::Streaming. Document 'render :text => proc { ... }' as a way to stream on-the-fly generated data to the browser.

actionpack/lib/action_controller/base.rb

@@ -784,9 +784,37 @@ def append_view_path(path)
       #   # placed in "app/views/layouts/special.r(html|xml)"
       #   render :text => "Hi there!", :layout => "special"
       #
-      # The <tt>:text</tt> option can also accept a Proc object, which can be used to manually control the page generation. This should
+      # === Streaming data and/or controlling the page generation
-      # generally be avoided, as it violates the separation between code and content, and because almost everything that can be
+      #
-      # done with this method can also be done more cleanly using one of the other rendering methods, most notably templates.
+      # The <tt>:text</tt> option can also accept a Proc object, which can be used to:
+      #
+      # 1. stream on-the-fly generated data to the browser. Note that you should
+      #    use the methods provided by ActionController::Steaming instead if you
+      #    want to stream a buffer or a file.
+      # 2. manually control the page generation. This should generally be avoided,
+      #    as it violates the separation between code and content, and because almost
+      #    everything that can be done with this method can also be done more cleanly
+      #    using one of the other rendering methods, most notably templates.
+      #
+      # Two arguments are passed to the proc, a <tt>response</tt> object and an
+      # <tt>output</tt> object. The response object is equivalent to the return
+      # value of the ActionController::Base#response method, and can be used to
+      # control various things in the HTTP response, such as setting the
+      # Content-Type header. The output object is an writable <tt>IO</tt>-like
+      # object, so one can call <tt>write</tt> and <tt>flush</tt> on it.
+      #
+      # The following example demonstrates how one can stream a large amount of
+      # on-the-fly generated data to the browser:
+      #
+      #   # Streams about 180 MB of generated data to the browser.
+      #   render :text => proc { |response, output|
+      #     10_000_000.times do |i|
+      #       output.write("This is line #{i}\n")
+      #       output.flush
+      #     end
+      #   }
+      #
+      # Another example:
       #
       #   # Renders "Hello from code!"
       #   render :text => proc { |response, output| output.write("Hello from code!") }

actionpack/lib/action_controller/streaming.rb

@@ -1,5 +1,6 @@
 module ActionController #:nodoc:
-  # Methods for sending files and streams to the browser instead of rendering.
+  # Methods for sending arbitrary data and for streaming files to the browser,
+  # instead of rendering.
   module Streaming
     DEFAULT_SEND_FILE_OPTIONS = {
       :type         => 'application/octet-stream'.freeze,
@@ -103,8 +104,11 @@ def send_file(path, options = {}) #:doc:
         end
       end
 
-      # Send binary data to the user as a file download.  May set content type, apparent file name,
+      # Sends the given binary data to the browser. This method is similar to
-      # and specify whether to show data inline or download as an attachment.
+      # <tt>render :text => data</tt>, but also allows you to specify whether
+      # the browser should display the response as a file attachment (i.e. in a
+      # download dialog) or as inline data. You may also set the content type,
+      # the apparent file name, and other things.
       #
       # Options:
       # * <tt>:filename</tt> - suggests a filename for the browser to use.
@@ -127,6 +131,10 @@ def send_file(path, options = {}) #:doc:
       #   send_data image.data, :type => image.content_type, :disposition => 'inline'
       #
       # See +send_file+ for more information on HTTP Content-* headers and caching.
+      #
+      # <b>Tip:</b> if you want to stream large amounts of on-the-fly generated
+      # data to the browser, then use <tt>render :text => proc { ... }</tt>
+      # instead. See ActionController::Base#render for more information.
       def send_data(data, options = {}) #:doc:
         logger.info "Sending data #{options[:filename]}" if logger
         send_file_headers! options.merge(:length => data.size)