shrine 2.3.1 → 2.4.0

data/lib/shrine.rb

@@ -4,9 +4,10 @@ require "securerandom"
 require "json"
 
 class Shrine
+  # A generic exception used by Shrine.
   class Error < StandardError; end
 
-  # Raised when a file was not a valid IO.
+  # Raised when a file is not a valid IO.
   class InvalidFile < Error
     def initialize(io, missing_methods)
       @io, @missing_methods = io, missing_methods
@@ -24,7 +25,7 @@ class Shrine
   end
 
   # Methods which an object has to respond to in order to be considered
-  # an IO object.  Keys are method names, and values are arguments.
+  # an IO object, along with their arguments.
   IO_METHODS = {
     :read   => [:length, :outbuf],
     :eof?   => [],
@@ -33,24 +34,24 @@ class Shrine
     :close  => [],
   }
 
-  # Core class that represents a file uploaded to a storage.  The instance
+  # Core class that represents a file uploaded to a storage. The instance
   # methods for this class are added by Shrine::Plugins::Base::FileMethods, the
   # class methods are added by Shrine::Plugins::Base::FileClassMethods.
   class UploadedFile
     @shrine_class = ::Shrine
   end
 
-  # Core class which generates attachment-specific modules that are included in
-  # model classes.  The instance methods for this class are added by
-  # Shrine::Plugins::Base::AttachmentMethods, the class methods are added by
-  # Shrine::Plugins::Base::AttachmentClassMethods.
+  # Core class which creates attachment modules for specified attribute names
+  # that are included into model classes. The instance methods for this class
+  # are added by Shrine::Plugins::Base::AttachmentMethods, the class methods
+  # are added by Shrine::Plugins::Base::AttachmentClassMethods.
   class Attachment < Module
     @shrine_class = ::Shrine
   end
 
-  # Core class which handles attaching files on records.  The instance methods
-  # for this class are added by Shrine::Plugins::Base::AttachmentMethods, the
-  # class methods are added by Shrine::Plugins::Base::AttachmentClassMethods.
+  # Core class which handles attaching files to model instances. The instance
+  # methods for this class are added by Shrine::Plugins::Base::AttacherMethods,
+  # the class methods are added by Shrine::Plugins::Base::AttacherClassMethods.
   class Attacher
     @shrine_class = ::Shrine
   end
@@ -63,8 +64,8 @@ class Shrine
   module Plugins
     @plugins = {}
 
-    # If the registered plugin already exists, use it.  Otherwise, require it
-    # and return it.  This raises a LoadError if such a plugin doesn't exist,
+    # If the registered plugin already exists, use it. Otherwise, require it
+    # and return it. This raises a LoadError if such a plugin doesn't exist,
     # or a Shrine::Error if it exists but it does not register itself
     # correctly.
     def self.load_plugin(name)
@@ -76,7 +77,7 @@ class Shrine
     end
 
     # Register the given plugin with Shrine, so that it can be loaded using
-    # `Shrine.plugin` with a symbol.  Should be used by plugin files. Example:
+    # `Shrine.plugin` with a symbol. Should be used by plugin files. Example:
     #
     #     Shrine::Plugins.register_plugin(:plugin_name, PluginModule)
     def self.register_plugin(name, mod)
@@ -91,11 +92,11 @@ class Shrine
         # Generic options for this class, plugins store their options here.
         attr_reader :opts
 
-        # A hash of storages and their symbol identifiers.
+        # A hash of storages with their symbol identifiers.
         attr_accessor :storages
 
         # When inheriting Shrine, copy the instance variables into the subclass,
-        # and setup the subclasses for core classes.
+        # and create subclasses of core classes.
         def inherited(subclass)
           subclass.instance_variable_set(:@opts, opts.dup)
           subclass.opts.each do |key, value|
@@ -118,12 +119,12 @@ class Shrine
           subclass.const_set(:Attacher, attacher_class)
         end
 
-        # Load a new plugin into the current class.  A plugin can be a module
-        # which is used directly, or a symbol represented a registered plugin
-        # which will be required and then used. Returns nil.
+        # Load a new plugin into the current class. A plugin can be a module
+        # which is used directly, or a symbol representing a registered plugin
+        # which will be required and then loaded.
         #
-        #     Shrine.plugin PluginModule
-        #     Shrine.plugin :basic_authentication
+        #     Shrine.plugin MyPlugin
+        #     Shrine.plugin :my_plugin
         def plugin(plugin, *args, &block)
           plugin = Plugins.load_plugin(plugin) if plugin.is_a?(Symbol)
           plugin.load_dependencies(self, *args, &block) if plugin.respond_to?(:load_dependencies)
@@ -139,35 +140,33 @@ class Shrine
           nil
         end
 
-        # Retrieves the storage specifies by the symbol/string, and raises an
-        # appropriate error if the storage is missing
+        # Retrieves the storage under the given identifier (can be a Symbol or
+        # a String), and raises Shrine::Error if the storage is missing.
         def find_storage(name)
           storages.each { |key, value| return value if key.to_s == name.to_s }
           raise Error, "storage #{name.inspect} isn't registered on #{self}"
         end
 
         # Generates an instance of Shrine::Attachment to be included in the
-        # model class.  Example:
+        # model class. Example:
         #
-        #     class User
-        #       include Shrine[:avatar] # alias for `Shrine.attachment(:avatar)`
+        #     class Photo
+        #       include Shrine[:image] # creates a Shrine::Attachment object
         #     end
         def attachment(name)
           self::Attachment.new(name)
         end
         alias [] attachment
 
-        # Instantiates a Shrine::UploadedFile from a JSON string or a hash, and
-        # optionally yields the returned objects (useful with versions).  This
-        # is used internally by Shrine::Attacher, but it's also useful when you
-        # need to deserialize the uploaded file in background jobs.
+        # Instantiates a Shrine::UploadedFile from a hash, and optionally
+        # yields the returned object.
         #
-        #     uploaded_file #=> #<Shrine::UploadedFile>
-        #     json = uploaded_file.to_json #=> '{"storage":"cache","id":"...","metadata":{...}}'
-        #     Shrine.uploaded_file(json) #=> #<Shrine::UploadedFile>
+        #     data = {"storage" => "cache", "id" => "abc123.jpg", "metadata" => {}}
+        #     Shrine.uploaded_file(data) #=> #<Shrine::UploadedFile>
         def uploaded_file(object, &block)
           case object
           when String
+            warn "Giving a string to Shrine.uploaded_file is deprecated and won't be possible in Shrine 3. Use Attacher#uploaded_file instead."
             uploaded_file(JSON.parse(object), &block)
           when Hash
             uploaded_file(self::UploadedFile.new(object), &block)
@@ -180,10 +179,10 @@ class Shrine
       end
 
       module InstanceMethods
-        # The symbol that identifies the storage.
+        # The symbol identifier for the storage used by the uploader.
         attr_reader :storage_key
 
-        # The storage object identified by #storage_key.
+        # The storage object used by the uploader.
         attr_reader :storage
 
         # Accepts a storage symbol registered in `Shrine.storages`.
@@ -192,33 +191,28 @@ class Shrine
           @storage_key = storage_key.to_sym
         end
 
-        # The class-level options hash.  This should probably not be modified
-        # at the instance level.
+        # The class-level options hash. This should probably not be modified at
+        # the instance level.
         def opts
           self.class.opts
         end
 
-        # The main method for uploading files.  Takes in an IO object and an
-        # optional context (used internally by Shrine::Attacher).  It calls
-        # user-defined #process, and aferwards it calls #store.  The `io` is
+        # The main method for uploading files. Takes an IO-like object and an
+        # optional context hash (used internally by Shrine::Attacher). It calls
+        # user-defined #process, and aferwards it calls #store. The `io` is
         # closed after upload.
         def upload(io, context = {})
           io = processed(io, context) || io
           store(io, context)
         end
 
-        # User is expected to perform processing inside of this method, and
+        # User is expected to perform processing inside this method, and
         # return the processed files. Returning nil signals that no proccessing
         # has been done and that the original file should be used.
         #
         #     class ImageUploader < Shrine
         #       def process(io, context)
-        #         case context[:action]
-        #         when :cache
-        #           # do processing
-        #         when :store
-        #           # do processing
-        #         end
+        #         # do processing and return processed files
         #       end
         #     end
         def process(io, context = {})
@@ -229,25 +223,26 @@ class Shrine
         # \#generate_location, but you can pass in `:location` to upload to
         # a specific location.
         #
-        #     uploader.store(io, location: "custom/location.jpg")
+        #     uploader.store(io)
         def store(io, context = {})
           _store(io, context)
         end
 
-        # Checks if the storage identified with this instance uploaded the
-        # given file.
+        # Returns true if the storage of the given uploaded file matches the
+        # storage of this uploader.
         def uploaded?(uploaded_file)
           uploaded_file.storage_key == storage_key.to_s
         end
 
-        # Deletes the given uploaded file.
+        # Deletes the given uploaded file and returns it.
         def delete(uploaded_file, context = {})
           _delete(uploaded_file, context)
           uploaded_file
         end
 
-        # Generates a unique location for the uploaded file, and preserves an
-        # optional extension.
+        # Generates a unique location for the uploaded file, preserving the
+        # file extension. Can be overriden in uploaders for generating custom
+        # location.
         def generate_location(io, context = {})
           extension   = ".#{io.extension}" if io.is_a?(UploadedFile) && io.extension
           extension ||= File.extname(extract_filename(io).to_s)
@@ -257,8 +252,7 @@ class Shrine
         end
 
         # Extracts filename, size and MIME type from the file, which is later
-        # accessible through `UploadedFile#metadata`. When the uploaded file
-        # is later promoted, this metadata is simply copied over.
+        # accessible through `UploadedFile#metadata`.
         def extract_metadata(io, context = {})
           {
             "filename"  => extract_filename(io),
@@ -269,7 +263,7 @@ class Shrine
 
         private
 
-        # Extracts the filename from the IO using some basic heuristics.
+        # Attempts to extract the appropriate filename from the IO object.
         def extract_filename(io)
           if io.respond_to?(:original_filename)
             io.original_filename
@@ -278,7 +272,7 @@ class Shrine
           end
         end
 
-        # Extracts the MIME type from the IO using some basic heuristics.
+        # Attempts to extract the MIME type from the IO object.
         def extract_mime_type(io)
           if io.respond_to?(:content_type)
             warn "The \"mime_type\" Shrine metadata field will be set from the \"Content-Type\" request header, which might not hold the actual MIME type of the file. It is recommended to load the determine_mime_type plugin which determines MIME type from file content." unless opts.key?(:mime_type_analyzer)
@@ -286,14 +280,16 @@ class Shrine
           end
         end
 
-        # Extracts the filesize from the IO.
+        # Extracts the filesize from the IO object.
         def extract_size(io)
           io.size
         end
 
-        # Called by #store.  It first generates the location if it wasn't
-        # already provided with the `:location` option.  Afterwards it extracts
-        # the metadata, stores the file, and returns a Shrine::UploadedFile.
+        # It first asserts that `io` is a valid IO object. It then extracts
+        # metadata and generates the location, before calling the storage to
+        # upload the IO object, passing the extracted metadata and location.
+        # Finally it returns a Shrine::UploadedFile object which represents the
+        # file that was uploaded.
         def _store(io, context)
           _enforce_io(io)
           metadata = get_metadata(io, context)
@@ -301,24 +297,26 @@ class Shrine
 
           put(io, context.merge(location: location, metadata: metadata))
 
-          self.class::UploadedFile.new(
+          self.class.uploaded_file(
             "id"       => location,
             "storage"  => storage_key.to_s,
             "metadata" => metadata,
           )
         end
 
-        # Removes the file. Called by #delete.
+        # Delegates to #remove.
         def _delete(uploaded_file, context)
           remove(uploaded_file, context)
         end
 
-        # Copies the file to the storage.
+        # Delegates to #copy.
         def put(io, context)
           copy(io, context)
         end
 
-        # Does the actual uploading, calling `#upload` on the storage.
+        # Calls `#upload` on the storage, passing to it the location, metadata
+        # and any upload options. The storage might modify the location or
+        # metadata that were passed in. The uploaded IO is then closed.
         def copy(io, context)
           location = context[:location]
           metadata = context[:metadata]
@@ -329,24 +327,24 @@ class Shrine
           io.close rescue nil
         end
 
-        # Does the actual deletion, calls `UploadedFile#delete`.
+        # Delegates to `UploadedFile#delete`.
         def remove(uploaded_file, context)
           uploaded_file.delete
         end
 
-        # Calls #process and returns the processed files.
+        # Delegates to #process.
         def processed(io, context)
           process(io, context)
         end
 
-        # Retrieves the location for the given io and context. First it looks
+        # Retrieves the location for the given IO and context. First it looks
         # for the `:location` option, otherwise it calls #generate_location.
         def get_location(io, context)
           context[:location] || generate_location(io, context)
         end
 
-        # Copies the metadata over from an UploadedFile or calls
-        # #extract_metadata.
+        # If the IO object is a Shrine::UploadedFile, it simply copies over its
+        # metadata, otherwise it calls #extract_metadata.
         def get_metadata(io, context)
           if io.is_a?(UploadedFile)
             io.metadata.dup
@@ -355,22 +353,24 @@ class Shrine
           end
         end
 
-        # Checks if the object is a valid IO by checking that it responds to
-        # `#read`, `#eof?`, `#rewind`, `#size` and `#close`, otherwise raises
-        # Shrine::InvalidFile.
+        # Asserts that the object is a valid IO object, specifically that it
+        # responds to `#read`, `#eof?`, `#rewind`, `#size` and `#close`. If the
+        # object doesn't respond to one of these methods, a Shrine::InvalidFile
+        # error is raised.
         def _enforce_io(io)
           missing_methods = IO_METHODS.select { |m, a| !io.respond_to?(m) }
           raise InvalidFile.new(io, missing_methods) if missing_methods.any?
         end
 
-        # Generates a UID to use in location for uploaded files.
+        # Generates a unique identifier that can be used for a location.
         def generate_uid(io)
           SecureRandom.hex
         end
       end
 
       module AttachmentClassMethods
-        # Reference to the Shrine class related to this attachment class.
+        # Returns the Shrine class that this attachment class is
+        # namespaced under.
         attr_accessor :shrine_class
 
         # Since Attachment is anonymously subclassed when Shrine is subclassed,
@@ -382,16 +382,13 @@ class Shrine
       end
 
       module AttachmentMethods
-        # Since Shrine::Attachment is a subclass of `Module`, this method
-        # generates a module, which should be included in a model class.
+        # Instantiates an attachment module for a given attribute name, which
+        # can then be included to a model class.
         def initialize(name)
           @name = name
 
-          # We store the attacher class so that it can be retrieved by the model
-          # at the instance level when instantiating the attacher.  We use a
-          # class variable because (a) it can be accessed from the instance
-          # level without needing to create a class-level reader, and (b) we
-          # want it to be inherited when subclassing the model
+          # We store the attacher class so that the model can instantiate the
+          # correct attacher instance.
           class_variable_set(:"@@#{name}_attacher_class", shrine_class::Attacher)
 
           module_eval <<-RUBY, __FILE__, __LINE__ + 1
@@ -413,21 +410,30 @@ class Shrine
           RUBY
         end
 
-        # Displays the attachment name.
+        # Includes the attachment name in the output.
         #
-        #     Shrine[:avatar] #=> #<Shrine::Attachment(avatar)>
+        #     Shrine[:image].to_s #=> "#<Shrine::Attachment(image)>"
+        def to_s
+          "#<#{self.class.inspect}(#{@name})>"
+        end
+
+        # Includes the attachment name in the output.
+        #
+        #     Shrine[:image].inspect #=> "#<Shrine::Attachment(image)>"
         def inspect
           "#<#{self.class.inspect}(#{@name})>"
         end
 
-        # Returns the Shrine class related to this attachment.
+        # Returns the Shrine class that this attachment's class is namespaced
+        # under.
         def shrine_class
           self.class.shrine_class
         end
       end
 
       module AttacherClassMethods
-        # Reference to the Shrine class related to this attacher class.
+        # Returns the Shrine class that this attacher class is namespaced
+        # under.
         attr_accessor :shrine_class
 
         # Since Attacher is anonymously subclassed when Shrine is subclassed,
@@ -438,7 +444,7 @@ class Shrine
         end
 
         # Block that is executed in context of Shrine::Attacher during
-        # validation.  Example:
+        # validation. Example:
         #
         #     Shrine::Attacher.validate do
         #       if get.size > 5*1024*1024
@@ -451,8 +457,22 @@ class Shrine
       end
 
       module AttacherMethods
-        attr_reader :cache, :store, :context, :errors
+        # Returns the uploader that is used for the temporary storage.
+        attr_reader :cache
+
+        # Returns the uploader that is used for the permanent storage.
+        attr_reader :store
+
+        # Returns the context that will be sent to the uploader when uploading
+        # and deleting. Can be modified with additional data to be sent to the
+        # uploader.
+        attr_reader :context
 
+        # Returns an array of validation errors created on file assignment in
+        # the `Attacher.validate` block.
+        attr_reader :errors
+
+        # Initializes the necessary attributes.
         def initialize(record, name, cache: :cache, store: :store)
           @cache   = shrine_class.new(cache)
           @store   = shrine_class.new(store)
@@ -462,13 +482,14 @@ class Shrine
 
         # Returns the model instance associated with the attacher.
         def record; context[:record]; end
+
         # Returns the attachment name associated with the attacher.
         def name;   context[:name];   end
 
-        # Receives the attachment value from the form.  If it receives a JSON
-        # string or a hash, it will assume this refrences an already cached
-        # file (e.g. when it persisted after validation errors).
-        # Otherwise it assumes that it's an IO object and caches it.
+        # Receives the attachment value from the form. It can receive an
+        # already cached file as a JSON string, otherwise it assumes that it's
+        # an IO object and uploads it to the temporary storage. The cached file
+        # is then written to the attachment attribute in the JSON format.
         def assign(value)
           if value.is_a?(String)
             return if value == "" || value == read || !cache.uploaded?(uploaded_file(value))
@@ -479,8 +500,9 @@ class Shrine
           end
         end
 
-        # Assigns a Shrine::UploadedFile, runs validation and schedules the
-        # old file for deletion.
+        # Accepts a Shrine::UploadedFile object and writes is to the attachment
+        # attribute. It then runs file validations, and records that the
+        # attachment has changed.
         def set(uploaded_file)
           @old = get
           _set(uploaded_file)
@@ -498,57 +520,58 @@ class Shrine
           instance_variable_defined?(:@old)
         end
 
-        # Plugins can override this if they want something to be done on save.
+        # Plugins can override this if they want something to be done before
+        # save.
         def save
         end
 
         # Deletes the old file and promotes the new one. Typically this should
-        # be called after saving.
+        # be called after saving the model instance.
         def finalize
           replace
           remove_instance_variable(:@old)
           _promote(action: :store) if cached?
         end
 
-        # Promotes the file.
+        # Delegates to #promote, overriden for backgrounding.
         def _promote(uploaded_file = get, **options)
           promote(uploaded_file, **options)
         end
 
-        # Uploads the cached file to store, and updates the record with the
-        # stored file.
+        # Uploads the cached file to store, and writes the stored file to the
+        # attachment attribute.
         def promote(uploaded_file = get, **options)
           stored_file = store!(uploaded_file, **options)
           result = swap(stored_file) or _delete(stored_file, action: :abort)
           result
         end
 
-        # Calls #update, overriden in ORM plugins.
+        # Calls #update, overriden in ORM plugins, and returns true if the
+        # attachment was successfully updated.
         def swap(uploaded_file)
           update(uploaded_file)
           uploaded_file if uploaded_file == get
         end
 
-        # Deletes the attachment that was replaced, and is called after saving
-        # by ORM integrations. If also removes `@old` so that #save and #finalize
-        # don't get called for the current attachment anymore.
+        # Deletes the previous attachment that was replaced, typically called
+        # after the model instance is saved with the new attachment.
         def replace
           _delete(@old, action: :replace) if @old && !cache.uploaded?(@old)
         end
 
-        # Deletes the attachment. Typically this should be called after
-        # destroying a record.
+        # Deletes the current attachment, typically called after destroying the
+        # record.
         def destroy
           _delete(get, action: :destroy) if get && !cache.uploaded?(get)
         end
 
-        # Deletes the uploaded file.
+        # Delegates to #delete!, overriden for backgrounding.
         def _delete(uploaded_file, **options)
           delete!(uploaded_file, **options)
         end
 
-        # Returns the URL to the attached file (internally calls `#url` on the
-        # storage), forwarding any URL options to the storage.
+        # Returns the URL to the attached file if it's present. It forwards any
+        # given URL options to the storage.
         def url(**options)
           get.url(**options) if read
         end
@@ -563,41 +586,55 @@ class Shrine
           get && store.uploaded?(get)
         end
 
-        # Retrieves the uploaded file from the record column.
+        # Returns a Shrine::UploadedFile instantiated from the data written to
+        # the attachment attribute.
         def get
           uploaded_file(read) if read
         end
 
-        # It reads from the record's `<attachment>_data` column.
+        # Reads from the `<attachment>_data` attribute on the model instance.
+        # It returns nil if the value is blank.
         def read
-          value = record.send(:"#{name}_data")
-          value unless value.nil? || value.empty?
+          value = record.send(data_attribute)
+          convert_after_read(value) unless value.nil? || value.empty?
         end
 
-        # Uploads the file to cache passing context.
+        # Uploads the file using the #cache uploader, passing the #context.
         def cache!(io, **options)
           warn "Sending :phase to Shrine::Attacher#cache! is deprecated and will not be supported in Shrine 3. Use :action instead." if options[:phase]
           cache.upload(io, context.merge(_equalize_phase_and_action(options)))
         end
 
-        # Uploads the file to store passing context.
+        # Uploads the file using the #store uploader, passing the #context.
         def store!(io, **options)
           warn "Sending :phase to Shrine::Attacher#store! is deprecated and will not be supported in Shrine 3. Use :action instead." if options[:phase]
           store.upload(io, context.merge(_equalize_phase_and_action(options)))
         end
 
-        # Deletes the file passing context.
+        # Deletes the file using the uploader, passing the #context.
         def delete!(uploaded_file, **options)
           warn "Sending :phase to Shrine::Attacher#delete! is deprecated and will not be supported in Shrine 3. Use :action instead." if options[:phase]
           store.delete(uploaded_file, context.merge(_equalize_phase_and_action(options)))
         end
 
-        # Delegates to `Shrine.uploaded_file`.
-        def uploaded_file(*args, &block)
-          shrine_class.uploaded_file(*args, &block)
+        # Enhances `Shrine.uploaded_file` with the ability to recognize uploaded
+        # files as JSON strings.
+        def uploaded_file(object, &block)
+          if object.is_a?(String)
+            uploaded_file(JSON.parse(object), &block)
+          else
+            shrine_class.uploaded_file(object, &block)
+          end
+        end
+
+        # The name of the attribute on the model instance that is used to store
+        # the attachment data. Defaults to `<attachment>_data`.
+        def data_attribute
+          :"#{name}_data"
         end
 
-        # Returns the Shrine class related to this attacher.
+        # Returns the Shrine class that this attacher's class is namespaced
+        # under.
         def shrine_class
           self.class.shrine_class
         end
@@ -609,24 +646,42 @@ class Shrine
           set(cached_file)
         end
 
-        # Sets and saves the uploaded file.
+        # Writes the uploaded file the attachment attribute. Overriden in ORM
+        # plugins to additionally save the model instance.
         def update(uploaded_file)
           _set(uploaded_file)
         end
 
-        # The validation block provided by `Shrine.validate`.
+        # The validation block registered with `Attacher.validate`.
         def validate_block
           shrine_class.opts[:validate]
         end
 
-        # It dumps the UploadedFile to JSON and writes the result to the column.
+        # Converts the UploadedFile to a data hash and writes it to the
+        # attribute.
         def _set(uploaded_file)
-          write(uploaded_file ? uploaded_file.to_json : nil)
+          write(uploaded_file ? convert_to_data(uploaded_file) : nil)
         end
 
-        # It writes to record's `<attachment>_data` column.
+        # Writes to the `<attachment>_data` attribute on the model instance.
         def write(value)
-          record.send(:"#{name}_data=", value)
+          value = convert_before_write(value) unless value.nil?
+          record.send(:"#{data_attribute}=", value)
+        end
+
+        # Returns the data hash of the given UploadedFile.
+        def convert_to_data(uploaded_file)
+          uploaded_file.data
+        end
+
+        # Returns the hash value dumped to JSON.
+        def convert_before_write(value)
+          value.to_json
+        end
+
+        # Returns the read value unchanged.
+        def convert_after_read(value)
+          value
         end
 
         # Temporary method used for transitioning from :phase to :action.
@@ -638,7 +693,7 @@ class Shrine
       end
 
       module FileClassMethods
-        # Reference to the Shrine class related to this uploaded file class.
+        # Returns the Shrine class that this file class is namespaced under.
         attr_accessor :shrine_class
 
         # Since UploadedFile is anonymously subclassed when Shrine is subclassed,
@@ -650,32 +705,32 @@ class Shrine
       end
 
       module FileMethods
-        # The entire data hash which identifies this uploaded file.
+        # The hash of information which defines this uploaded file.
         attr_reader :data
 
+        # Initializes the uploaded file with the given data hash.
         def initialize(data)
           @data = data
           @data["metadata"] ||= {}
           storage # ensure storage exists
         end
 
-        # The ID of the uploaded file, which holds the location of the actual
-        # file on the storage
+        # The location where the file was uploaded to the storage.
         def id
           @data.fetch("id")
         end
 
-        # The storage key as a string.
+        # The string identifier of the storage the file is uploaded to.
         def storage_key
           @data.fetch("storage")
         end
 
-        # A hash of metadata.
+        # A hash of file metadata that was extracted during upload.
         def metadata
           @data.fetch("metadata")
         end
 
-        # The filename that was extracted from the original file.
+        # The filename that was extracted from the uploaded file.
         def original_filename
           metadata["filename"]
         end
@@ -686,34 +741,34 @@ class Shrine
           File.extname(id)[1..-1] || File.extname(original_filename.to_s)[1..-1]
         end
 
-        # The filesize of the original file.
+        # The filesize of the uploaded file.
         def size
           (@io && @io.size) || (metadata["size"] && Integer(metadata["size"]))
         end
 
-        # The MIME type of the original file.
+        # The MIME type of the uploaded file.
         def mime_type
           metadata["mime_type"]
         end
         alias content_type mime_type
 
-        # Opens the underlying IO for reading and yields it to the block,
-        # closing it after the block finishes. Use #to_io for opening without a
-        # block.
+        # Opens an IO object of the uploaded file for reading and yields it to
+        # the block, closing it after the block finishes. For opening without
+        # a block #to_io can be used.
         #
         #     uploaded_file.open do |io|
-        #       # ...
+        #       puts io.read # prints the content of the file
         #     end
         def open
           @io = storage.open(id)
           yield @io
         ensure
-          @io.close
+          @io.close if @io
           @io = nil
         end
 
-        # Calls `#download` on the storage if it is implemented, otherwise
-        # streams the underlying IO to a Tempfile.
+        # Calls `#download` on the storage if the storage implements it,
+        # otherwise uses #open to stream the underlying IO to a Tempfile.
         def download
           if storage.respond_to?(:download)
             storage.download(id)
@@ -724,39 +779,37 @@ class Shrine
           end
         end
 
-        # Part of Shrine::UploadedFile's complying to the IO interface.  It
-        # delegates to the internally downloaded file.
+        # Part of complying to the IO interface. It delegates to the internally
+        # opened IO object.
         def read(*args)
           io.read(*args)
         end
 
-        # Part of Shrine::UploadedFile's complying to the IO interface.  It
-        # delegates to the internally downloaded file.
+        # Part of complying to the IO interface. It delegates to the internally
+        # opened IO object.
         def eof?
           io.eof?
         end
 
-        # Part of Shrine::UploadedFile's complying to the IO interface.  It
-        # delegates to the internally downloaded file.
+        # Part of complying to the IO interface. It delegates to the internally
+        # opened IO object.
         def close
-          if @io
-            io.close
-            io.delete if io.class.name == "Tempfile"
-          end
+          io.close if @io
         end
 
-        # Part of Shrine::UploadedFile's complying to the IO interface.  It
-        # delegates to the internally downloaded file.
+        # Part of complying to the IO interface. It delegates to the internally
+        # opened IO object.
         def rewind
           io.rewind
         end
 
-        # Calls `#url` on the storage, forwarding any options.
+        # Calls `#url` on the storage, forwarding any given URL options.
         def url(**options)
           storage.url(id, **options)
         end
 
-        # Calls `#exists?` on the storage, which checks that the file exists.
+        # Calls `#exists?` on the storage, which checks whether the file exists
+        # on the storage.
         def exists?
           storage.exists?(id)
         end
@@ -766,18 +819,19 @@ class Shrine
           uploader.upload(io, context.merge(location: id))
         end
 
-        # Calls `#delete` on the storage, which deletes the remote file.
+        # Calls `#delete` on the storage, which deletes the file from the
+        # storage.
         def delete
           storage.delete(id)
         end
 
-        # Returns the underlying IO.
+        # Returns an opened IO object for the uploaded file.
         def to_io
           io
         end
 
-        # Serializes the uploaded file to JSON, suitable for storing in the
-        # column or passing to a background job.
+        # Returns the data hash in the JSON format. Suitable for storing in a
+        # database column or passing to a background job.
         def to_json(*args)
           data.to_json(*args)
         end
@@ -787,8 +841,8 @@ class Shrine
           data
         end
 
-        # Two uploaded files are equal if they're uploaded to the same storage
-        # and they have the same #id.
+        # Returns true if the other UploadedFile is uploaded to the same
+        # storage and it has the same #id.
         def ==(other)
           other.is_a?(self.class) &&
           self.id == other.id &&
@@ -796,32 +850,30 @@ class Shrine
         end
         alias eql? ==
 
+        # Enables using UploadedFile objects as hash keys.
         def hash
           [id, storage_key].hash
         end
 
-        # The instance of `Shrine` with the corresponding storage.
+        # Returns an uploader object for the corresponding storage.
         def uploader
           shrine_class.new(storage_key)
         end
 
-        # The storage class this file was uploaded to.
+        # Returns the storage that this file was uploaded to.
         def storage
           shrine_class.find_storage(storage_key)
         end
 
-        # Returns the Shrine class related to this uploaded file.
+        # Returns the Shrine class that this file's class is namespaced under.
         def shrine_class
           self.class.shrine_class
         end
 
-        # Show only the data hash in inspect output.
-        def inspect
-          "#{to_s.chomp(">")} @data=#{data.inspect}>"
-        end
-
         private
 
+        # Returns an opened IO object for the uploaded file by calling `#open`
+        # on the storage.
         def io
           @io ||= storage.open(id)
         end