Document Marcel::MimeType.for

on-behalf-of: @Cofense <oss@cofense.com>

README.md

@@ -43,6 +43,8 @@ Marcel::MimeType.for Pathname.new("example.png"), name: "example.ai"
 # As "application/illustrator" is not a more specific type of "image/png", the filename is ignored
 ```
 
+`Marcel::MimeType.for` is Marcel's only public interface.
+
 ## Motivation
 
 Marcel was extracted from Basecamp 3, in order to make our file detection logic both easily reusable but more importantly, easily testable. Test fixtures have been added for all of the most common file types uploaded to Basecamp, and other common file types too. We hope to expand this test coverage with other file types as and when problems are identified.

lib/marcel/mime_type.rb

@@ -13,6 +13,21 @@ def extend(type, extensions: [], parents: [], magic: nil)
         Magic.add(type, extensions: extensions, magic: magic, parents: parents, comment: comment)
       end
 
+      # Returns the most appropriate content type for the given file.
+      #
+      # The first argument should be a +Pathname+ or an +IO+. If it is a +Pathname+, the specified
+      # file will be opened first.
+      #
+      # Optional parameters:
+      # * +name+: file name, if known
+      # * +extension+: file extension, if known
+      # * +declared_type+: MIME type, if known
+      #
+      # The most appropriate type is the more specific of the following:
+      #   * type determined by the magic number
+      #   * type determined by the first of file name, file extension, or declared MIME type
+      #
+      # If no type can be determined, the most appropriate type is +application/octet-stream+.
       def for(pathname_or_io = nil, name: nil, extension: nil, declared_type: nil)
         type_from_data = for_data(pathname_or_io)
         fallback_type = for_declared_type(declared_type) || for_name(name) || for_extension(extension) || BINARY