Fix Dialyzer issues and add missing docs

Author: JohnDoneth

lib/upload.ex

@@ -3,6 +3,8 @@ defmodule Upload do
   An opinionated file uploader.
   """
 
+  @type variant_id :: String.t() | atom()
+
   alias Upload.Blob
   alias Upload.Stat
 
@@ -37,7 +39,16 @@ defmodule Upload do
     end
   end
 
-  @spec variant_exists?(Blob.t(), String.t() | atom()) :: boolean()
+  @doc """
+  Checks if a variant exists for a given `Upload.Blob` and the variant identifier.
+
+  ## Example
+
+      iex> Upload.variant_exists?(person.avatar, :small)
+      iex> true
+
+  """
+  @spec variant_exists?(Blob.t(), variant_id()) :: boolean()
   def variant_exists?(%Blob{id: blob_id}, variant) do
     repo = Upload.Config.repo()
 
@@ -46,7 +57,17 @@ defmodule Upload do
     |> repo.exists?()
   end
 
-  @spec get_variant(Blob.t(), String.t() | atom()) :: nil | Blob.t()
+  @doc """
+  Returns the variant for a given `Upload.Blob` and the variant identifier or `nil` if it
+  does not exist.
+
+  ## Example
+
+      iex> Upload.get_variant(person.avatar, :small)
+      %Blob{}
+
+  """
+  @spec get_variant(Blob.t(), variant_id()) :: nil | Blob.t()
   def get_variant(%Blob{id: blob_id}, variant) do
     repo = Upload.Config.repo()
 
@@ -64,13 +85,13 @@ defmodule Upload do
 
   ## Example
 
-  ```elixir
-  create_variant(original_blob, "small", &transform_fn/3)
-  ```
+      iex> create_variant(original_blob, :small, &transform_fn/3)
+      {:ok, %Blob{}}
   """
   @spec create_variant(Blob.t(), String.t(), any()) :: {:ok, Blob.t()} | {:error, any()}
   def create_variant(original_blob, variant, transform_fn) when is_function(transform_fn, 3) do
     repo = Upload.Config.repo()
+    variant = to_string(variant)
 
     {:ok, multi_result} =
       Ecto.Multi.new()
@@ -87,13 +108,14 @@ defmodule Upload do
 
   ## Example
 
-  ```elixir
-  create_multiple_variants(blob, ["small", "large"], &transform_fn/3)
-  ```
+      iex> create_multiple_variants(blob, [:small, :large], &transform_fn/3)
+      {:ok, [%Blob{...}, %Blob{...}]}
   """
-  @spec create_multiple_variants(Blob.t(), [String.t()], any()) :: any()
+  @spec create_multiple_variants(Blob.t(), [variant_id()], any()) ::
+          {:ok, [Blob.t()]} | {:error, any()}
   def create_multiple_variants(original_blob, variants, transform_fn)
       when is_function(transform_fn, 3) do
+    variants = Enum.map(variants, &to_string/1)
     repo = Upload.Config.repo()
     multi = Ecto.Multi.new()
 
@@ -116,26 +138,32 @@ defmodule Upload do
   @doc """
   Set the visiblity of a `Blob` using the struct or it's key.
 
-  This only applies when Upload is configured to use S3.
+  > #### Note {: .warning}
+  >
+  > This only applies when Upload is configured to use S3.
 
-  Supported access control lists for Amazon S3 are:
+  Supported canned access control lists for Amazon S3 are:
 
   | ACL                          | Permissions Added to ACL                                                        |
   |------------------------------|---------------------------------------------------------------------------------|
-  | "private"                    | Owner gets `FULL_CONTROL`. No one else has access rights (default).             |
-  | "public_read"                | Owner gets `FULL_CONTROL`. The `AllUsers` group gets READ access.               |
-  | "public_read_write"          | Owner gets `FULL_CONTROL`. The `AllUsers` group gets `READ` and `WRITE` access. |
-  |                              | Granting this on a bucket is generally not recommended.                         |
-  | "authenticated_read"         | Owner gets `FULL_CONTROL`. The `AuthenticatedUsers` group gets `READ` access.   |
-  | "bucket_owner_read"          | Object owner gets `FULL_CONTROL`. Bucket owner gets `READ` access.              |
-  | "bucket_owner_full_control"  | Both the object owner and the bucket owner get `FULL_CONTROL` over the object.  |
+  | private                      | Owner gets `FULL_CONTROL`. No one else has access rights (default).             |
+  | public_read                  | Owner gets `FULL_CONTROL`. The `AllUsers` group gets READ access.               |
+  | public_read_write            | Owner gets `FULL_CONTROL`. The `AllUsers` group gets `READ` and `WRITE` access. Granting this on a bucket is generally not recommended. |
+  | authenticated_read           | Owner gets `FULL_CONTROL`. The `AuthenticatedUsers` group gets `READ` access.   |
+  | bucket_owner_read            | Object owner gets `FULL_CONTROL`. Bucket owner gets `READ` access.              |
+  | bucket_owner_full_control    | Both the object owner and the bucket owner get `FULL_CONTROL` over the object.  |
+
+  ## Example
+
+      iex> Upload.put_access_control_list(person.avatar, :public_read)
+      :ok
   """
   @spec put_access_control_list(Blob.t() | Blob.key(), String.t()) :: :ok | {:error, term()}
-  def put_access_control_list(%Blob{key: key}, acl) do
-    put_access_control_list(key, acl)
+  def put_access_control_list(%Blob{key: key} = _blob, canned_acl) do
+    put_access_control_list(key, canned_acl)
   end
 
-  def put_access_control_list(key, acl) do
-    Upload.Storage.put_access_control_list(key, acl)
+  def put_access_control_list(key, canned_acl) do
+    Upload.Storage.put_access_control_list(key, [{:acl, canned_acl}])
   end
 end

lib/upload/blob.ex

@@ -77,7 +77,7 @@ defmodule Upload.Blob do
     mime = get_field(changeset, :content_type)
     extension = MIME.extensions(mime) |> List.first()
 
-    if mime && extension do
+    if extension do
       update_change(changeset, :key, fn key ->
         key <> "." <> extension
       end)
@@ -88,6 +88,7 @@ defmodule Upload.Blob do
 
   defp add_extension_from_mime(changeset), do: changeset
 
+  @doc false
   def change_blob(%Stat{} = stat, key) do
     changeset(
       %__MODULE__{},

lib/upload/changeset.ex

@@ -1,8 +1,12 @@
 defmodule Upload.Changeset do
   @moduledoc """
-  Functions to use with changesets to upload an attachment on a schema.
+  Functions for use with changesets to upload and validate attachments.
 
   ```elixir
+  schema "people" do
+    belongs_to(:avatar, Upload.Blob, on_replace: :delete, type: :binary_id)
+  end
+
   %Person{}
   |> Person.changeset(%{avatar: upload})
   |> cast_attachment(:avatar, required: true)
@@ -30,26 +34,38 @@ defmodule Upload.Changeset do
     terabyte: 1.0e12
   }
 
-  @spec put_attachment(changeset(), field(), Plug.Upload.t(), String.t()) :: changeset()
-  defp put_attachment(changeset, field, %Plug.Upload{} = upload, key) do
+  @spec put_attachment(changeset(), field(), Plug.Upload.t() | Upload.Stat.t(), String.t()) ::
+          changeset()
+  def put_attachment(changeset, field, %Plug.Upload{} = upload, key) do
     put_attachment(changeset, field, Upload.stat!(upload), key)
   end
 
-  @spec put_attachment(changeset(), field(), Upload.Stat.t(), String.t()) :: changeset()
-  defp put_attachment(changeset, field, %Upload.Stat{} = stat, key) do
+  def put_attachment(changeset, field, %Upload.Stat{} = stat, key) do
     put_assoc(changeset, field, Upload.Blob.change_blob(stat, key))
   end
 
-  @spec put_attachment(changeset(), field(), Ecto.Changeset.t(), String.t()) :: changeset()
-  defp put_attachment(changeset, field, %Ecto.Changeset{} = blob_changeset, key) do
-    put_assoc(changeset, field, blob_changeset |> put_change(:key, key))
-  end
-
   @spec put_attachment(changeset(), field(), Upload.Blob.t()) :: changeset()
   def put_attachment(changeset, field, %Upload.Blob{} = blob) do
     put_assoc(changeset, field, blob)
   end
 
+  @doc """
+  Adds an attachment to the changeset changes.
+
+  ## Options
+
+    * `:required` - Require the attachment.
+    * `:key_function` - A 1-arity function that is given the changeset and is
+      expected to return the path of the attachment in external storage without
+      the file type extension.
+
+  ## Example
+
+      iex> Upload.Changeset.cast_attachment(changeset, :avatar)
+
+      iex> Upload.Changeset.cast_attachment(changeset, :avatar, required: true, key_function: &key_function/1)
+
+  """
   @spec cast_attachment(changeset(), field(), cast_opts()) :: changeset()
   def cast_attachment(changeset, field, opts \\ []) do
     key =
@@ -96,7 +112,16 @@ defmodule Upload.Changeset do
     end)
   end
 
-  @spec validate_attachment_type(changeset, field, type_opts) :: changeset
+  @doc """
+  Require that the attachment is of a specific MIME type. This is determined by
+  looking at the file's contents and can be trusted.
+
+  ## Example
+
+      iex> validate_attachment_type(changeset, :avatar, allow: ["image/jpeg", "image/png"])
+
+  """
+  @spec validate_attachment_type(changeset(), field(), type_opts()) :: changeset()
   def validate_attachment_type(changeset, field, opts) do
     {message, opts} = Keyword.pop(opts, :message, "is not a supported file type")
 
@@ -109,6 +134,14 @@ defmodule Upload.Changeset do
     end)
   end
 
+  @doc """
+  Require that the attachment size is in a specific range.
+
+  ## Example
+
+      iex> validate_attachment_size(changeset, :avatar, smaller_than: {1, :megabyte})
+
+  """
   @spec validate_attachment_size(changeset, field, size_opts) :: changeset
   def validate_attachment_size(changeset, field, opts) do
     size = {number, unit} = Keyword.fetch!(opts, :smaller_than)

lib/upload/stat.ex

@@ -1,5 +1,5 @@
 defmodule Upload.Stat do
-  @moduledoc false
+  @moduledoc "Metadata of a given file"
   defstruct [:path, :filename, :byte_size, :checksum, :metadata, :content_type]
 
   @chunk_size 2_048

mix.exs

@@ -50,8 +50,7 @@ defmodule Upload.Mixfile do
       {:cloak, "~> 1.1.4"},
       {:ecto_sql, "~> 3.8"},
       {:ecto, "~> 3.6"},
-      {:file_store,
-       git: "https://github.com/joydrive/file_store.git", branch: "jd-add-acl-support"},
+      {:file_store, git: "https://github.com/joydrive/file_store.git", sha: "2ce496f"},
       {:file_type, "~> 0.1"},
       {:image, "~> 0.48"},
       {:plug, "~> 1.13"},
@@ -61,7 +60,7 @@ defmodule Upload.Mixfile do
       # Test dependencies for this package
       {:credo, "~> 1.7", only: [:dev, :test], runtime: false},
       {:dialyxir, "~> 1.4", only: [:dev, :test], runtime: false},
-      {:ex_doc, "~> 0.22", only: :dev, runtime: false},
+      {:ex_doc, "~> 0.34", only: :dev, runtime: false},
       {:excoveralls, "~> 0.18", only: :test},
       {:mix_test_watch, "~> 1.0", only: :dev, runtime: false}
     ]