Add explanation of MimeType.for's handling of argument types #68
Conversation
README.md
Outdated
| @@ -2,6 +2,8 @@ | |||
|
|
|||
| Marcel attempts to choose the most appropriate content type for a given file by looking at the binary data, the filename, and any declared type (perhaps passed as a request header): | |||
|
|
|||
| The primary interface is the method `Marcel::MimeType.for`. If the first argument is a `Pathname`, Marcel will evaluate the contents of the specified file. Any other type is assumed to be an `IO`, and Marcel will evaluate its contents. | |||
There was a problem hiding this comment.
I don't think this really fits the tone of the documentation. Let's make the following changes instead:
- Reword the starting sentences to this: "Marcel attempts to choose the most appropriate content type for a given file by looking at the binary data, the filename, and any declared type (perhaps passed as a request header). It's used like this:"
- Add an example above the motivation section with something like "Marcel expects either a
PathnameorIOobject to read content type data from:Marcel::MimeType.for Object.new # => "application/octet-stream"" - Document the
Marcel::MimeType.formethod.
There was a problem hiding this comment.
Thanks for the comments.
👍 to documenting Marcel::MimeType.for.
I'm not sure I understand the value of the second bullet point. As a new user, the question I had that motivated this PR was: I want to know all of the ways to use this gem so I can select the one that fits my needs. It turns out that the gem offers exactly one public interface, but that wasn't spelled out explicitly in the README. I instead propose a sentence at the end of the first section doing so.
elebow
force-pushed
the
readme-explain-for-pathname-argument
branch
from
77e7157
to
94f7d9c
Compare
README.md
Outdated
| @@ -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. | |||
There was a problem hiding this comment.
Marcel::MimeType.extend and Marcel::Magic are all public API as well, so that sentence isn't right. The gist is that Marcel::MimeType.for is how the gem is used to identify mimes, so we can compromise on that. Let's amend the the beginning sentence to: "Marcel attempts to choose the most appropriate content type for a given file by looking at the binary data, the filename, and any declared type (perhaps passed as a request header). This is done via the Marcel::MimeType.for method, and is used like this:"
There was a problem hiding this comment.
Sounds good to me. Changes pushed.
elebow
force-pushed
the
readme-explain-for-pathname-argument
branch
from
d911502
to
9160594
Compare
on-behalf-of: @Cofense <oss@cofense.com>
elebow
force-pushed
the
readme-explain-for-pathname-argument
branch
from
1635990
to
d2b6e39
Compare
|
Squashed. |
Adds an explicit statement that Marcel's primary interface is
Marcel::MimeType.for, and that the first argument is handled differently depending on whether it is aPathname. This information was previously present in the Readme, but only indirectly through the code examples.