Add documentation of content-type detection strategy

Also refactored to make the strategy hierarchy clearer

lib/paperclip/content_type_detector.rb

 module Paperclip
 module Paperclip
   class ContentTypeDetector
   class ContentTypeDetector
+    # The content-type detection strategy is as follows:
+    #
+    # 1. Blank/Empty files: If there's no filename or the file is empty, provide a sensible default
+    #    (application/octet-stream or inode/x-empty)
+    #
+    # 2. Uploaded file: Use the uploaded file's content type if it is in the list of mime-types
+    #    for the file's extension
+    #
+    # 3. Standard types: Return the first standard (without an x- prefix) entry in the list of
+    #    mime-types
+    #
+    # 4. Experimental types: If there were no standard types in the mime-types list, try to return
+    #    the first experimental one
+    #
+    # 5. Unrecognized extension: Use the file's content type or a sensible default if there are
+    #    no entries in mime-types for the extension
+    #
+    
     EMPTY_TYPE = "inode/x-empty"
     EMPTY_TYPE = "inode/x-empty"
     SENSIBLE_DEFAULT = "application/octet-stream"
     SENSIBLE_DEFAULT = "application/octet-stream"
 
 
@@ -7,17 +25,16 @@ module Paperclip
       @filename = filename
       @filename = filename
     end
     end
 
 
+    # Returns a String describing the file's content type
     def detect
     def detect
       if blank_name?
       if blank_name?
         SENSIBLE_DEFAULT
         SENSIBLE_DEFAULT
       elsif empty_file?
       elsif empty_file?
         EMPTY_TYPE
         EMPTY_TYPE
-      elsif !match?
-        type_from_file_command
-      elsif !multiple?
-        possible_types.first
+      elsif best_from_possible_types
+        best_from_possible_types.content_type
       else
       else
-        best_type_match
+        type_from_file_command || SENSIBLE_DEFAULT
       end.to_s
       end.to_s
     end
     end
 
 
@@ -30,23 +47,25 @@ module Paperclip
     def blank_name?
     def blank_name?
       @filename.nil? || @filename.empty?
       @filename.nil? || @filename.empty?
     end
     end
+    
+    def empty?
+      File.exists?(@filename) && File.size(@filename) == 0
+    end
 
 
     def possible_types
     def possible_types
       @possible_types ||= MIME::Types.type_for(@filename)
       @possible_types ||= MIME::Types.type_for(@filename)
     end
     end
-
-    def match?
-      possible_types.length > 0
+    
+    def official_types
+      @official_types ||= possible_types.reject {|type| type.content_type.match(/\/x-/) }
     end
     end
-
-    def multiple?
-      possible_types.length > 1
+    
+    def types_matching_file
+      possible_types.select{|type| type.content_type == type_from_file_command}
     end
     end
-
-    def best_type_match
-      types_matching_file = possible_types.select {|type| type.content_type == type_from_file_command}
-      official_types = possible_types.reject {|type| type.content_type.match(/\/x-/) }
-      (types_matching_file.first || official_types.first || possible_types.first).content_type
+    
+    def best_from_possible_types
+      @best_from_possible_types ||= (types_matching_file.first || official_types.first || possible_types.first)
     end
     end
 
 
     def type_from_file_command
     def type_from_file_command