documents ActionDispatch::Http::UploadedFile

1 files changed, 55 insertions, 6 deletions

diff --git a/actionpack/lib/action_dispatch/http/upload.rb b/actionpack/lib/action_dispatch/http/upload.rb
index d50c8cad17..79437d6e85 100644
--- a/actionpack/lib/action_dispatch/http/upload.rb
+++ b/actionpack/lib/action_dispatch/http/upload.rb
@@ -1,9 +1,28 @@
 module ActionDispatch
   module Http
+    # Models uploaded files.
+    #
+    # The actual file is accessible via the +tempfile+ accessor, though some
+    # of its interface is available directly for convenience.
+    #
+    # Uploaded files are temporary files whose lifespan is one request. When
+    # the object is finalized Ruby unlinks the file, so there is not need to
+    # clean them with a separate maintenance task.
     class UploadedFile
-      attr_accessor :original_filename, :content_type, :tempfile, :headers
+      # The basename of the file in the client.
+      attr_accessor :original_filename
 
-      def initialize(hash)
+      # A string with the MIME type of the file.
+      attr_accessor :content_type
+
+      # A +Tempfile+ object with the actual uploaded file. Note that some of
+      # its interface is available directly.
+      attr_accessor :tempfile
+
+      # TODO.
+      attr_accessor :headers
+
+      def initialize(hash) # :nodoc:
         @tempfile          = hash[:tempfile]
         raise(ArgumentError, ':tempfile is required') unless @tempfile
 
@@ -12,9 +31,39 @@ module ActionDispatch
         @headers           = hash[:head]
       end
 
-      # Delegate these methods to the tempfile.
-      [:read, :open, :close, :path, :rewind, :size, :eof?].each do |method|
-        class_eval "def #{method}(*args); @tempfile.#{method}(*args); end"
+      # Shortcut for +tempfile.read+.
+      def read(length=nil, buffer=nil)
+        @tempfile.read(length, buffer)
+      end
+
+      # Shortcut for +tempfile.open+.
+      def open
+        @tempfile.open
+      end
+
+      # Shortcut for +tempfile.close+.
+      def close(unlink_now=false)
+        @tempfile.close(unlink_now)
+      end
+
+      # Shortcut for +tempfile.path+.
+      def path
+        @tempfile.path
+      end
+
+      # Shortcut for +tempfile.rewind+.
+      def rewind
+        @tempfile.rewind
+      end
+
+      # Shortcut for +tempfile.size+.
+      def size
+        @tempfile.size
+      end
+
+      # Shortcut for +tempfile.eof?+.
+      def eof?
+        @tempfile.eof?
       end
 
       private
@@ -25,7 +74,7 @@ module ActionDispatch
       end
     end
 
-    module Upload
+    module Upload # :nodoc:
       # Convert nested Hash to HashWithIndifferentAccess and replace
       # file upload hash with UploadedFile objects
       def normalize_parameters(value)