RawResponse: always reopen tempfile for reading.

The user will presumably always want to read the tempfile that we have
downloaded, so we should preemptively reopen it for them rather than
leaving it closed.

Also add some method docs.

lib/restclient/abstract_response.rb

@@ -36,6 +36,9 @@ module RestClient
       @raw_headers ||= @net_http_res.to_hash
     end
 
+    # @param [Net::HTTPResponse] net_http_res
+    # @param [RestClient::Request] request
+    # @param [Time] start_time
     def response_set_vars(net_http_res, request, start_time)
       @net_http_res = net_http_res
       @request = request

lib/restclient/raw_response.rb

@@ -19,9 +19,16 @@ module RestClient
       "<RestClient::RawResponse @code=#{code.inspect}, @file=#{file.inspect}, @request=#{request.inspect}>"
     end
 
+    # @param [Tempfile] tempfile The temporary file containing the body
+    # @param [Net::HTTPResponse] net_http_res
+    # @param [RestClient::Request] request
+    # @param [Time] start_time
     def initialize(tempfile, net_http_res, request, start_time=nil)
       @file = tempfile
 
+      # reopen the tempfile so we can read it
+      @file.open
+
       response_set_vars(net_http_res, request, start_time)
     end
 
@@ -30,7 +37,7 @@ module RestClient
     end
 
     def body
-      @file.open
+      @file.rewind
       @file.read
     end
 

lib/restclient/request.rb

@@ -826,9 +826,6 @@ module RestClient
     # @param start_time [Time] Time of request start
     def process_result(res, start_time, tempfile, &block)
       if @raw_response
-        unless tempfile
-          raise ArgumentError.new('tempfile required if @raw_response true')
-        end
         # We don't decode raw requests
         response = RawResponse.new(tempfile, res, self, start_time)
       else

lib/restclient/response.rb

@@ -38,6 +38,14 @@ module RestClient
       "<RestClient::Response #{code.inspect} #{body_truncated(10).inspect}>"
     end
 
+    # Initialize a Response object. Because RestClient::Response is
+    # (unfortunately) a subclass of String for historical reasons,
+    # Response.create is the preferred initializer.
+    #
+    # @param [String, nil] body The response body from the Net::HTTPResponse
+    # @param [Net::HTTPResponse] net_http_res
+    # @param [RestClient::Request] request
+    # @param [Time] start_time
     def self.create(body, net_http_res, request, start_time=nil)
       result = self.new(body || '')
 
@@ -47,6 +55,8 @@ module RestClient
       result
     end
 
+    # Set the String encoding according to the 'Content-Type: charset' header,
+    # if possible.
     def self.fix_encoding(response)
       charset = RestClient::Utils.get_encoding_from_headers(response.headers)
       encoding = nil