image: write documentation

Author: Sorixelle

lib/data/collection.ex

@@ -5,7 +5,7 @@ defmodule Memorable.Data.Collection do
   Collections can be thought of as analogous to a photo album, or a gallery. They are the primary mechanism for
   organizing images.
 
-  Collections are comprised of the following fields:
+  ## Fields
   - `id`: An [ID](`t:Memorable.Util.id/0`) representing the collection
   - `name`: The human-readable name of the collection
   - `created_datetime`: A `DateTime` representing the time at which the collection was created.

lib/data/image.ex

@@ -1,4 +1,22 @@
 defmodule Memorable.Data.Image do
+  @moduledoc """
+  Functions for working with images in memorable.
+
+  An `Image` represents one image stored in a memorable `Collection`. Images are always associated with exactly one
+  collection - it is not possible for one image to be a part of two different collections.
+
+  ## Structure
+  The `Image` struct holds information about an image relevant to storage and relations. It does not contain other
+  metadata about the image itself, such as when the photo was taken or other data stored in the image's EXIF tags. These
+  are instead kept in the `Memorable.Data.Image.DerivedMetadata` table.
+
+  ## Fields
+  - `id`: An [ID](`t:Memorable.Util.id/0`) representing the image.
+  - `collection_id`: The [ID](`t:Memorable.Util.id/0`) of the `Memorable.Data.Collection` the image is a part of.
+  - `path`: The path to the image file on disk, relative to the folder memorable stores all images in.
+  - `imported_datetime`: A `DateTime` representing the time at which the image was imported into the memorable database.
+  """
+  @moduledoc since: "1.0.0"
   @derive {Inspect, except: []}
   use Memento.Table, attributes: [:id, :collection_id, :path, :imported_datetime]
 
@@ -10,6 +28,15 @@ defmodule Memorable.Data.Image do
         }
   @type metadata :: %{String.t() => any()}
 
+  @doc """
+  Reads metadata from the image.
+
+  To get metadata from the image, memorable calls out to `exiftool` installed on the system to obtain all EXIF tags
+  stored on the image. See `Subprocess`, or the code in `native/subprocess` for details on how this is done.
+
+  Returns a map from EXIF tags to their values, for all tags in the image.
+  """
+  @doc since: "1.0.0"
   @spec read_metadata(t()) :: {:ok, metadata()} | {:error, any()}
   def read_metadata(%__MODULE__{path: path}) do
     with {:file_read, {:ok, data}} <- {:file_read, File.read(path)},
@@ -26,6 +53,32 @@ defmodule Memorable.Data.Image do
 end
 
 defmodule Memorable.Data.Image.DerivedMetadata do
+  @moduledoc """
+  Metadata associated with images.
+
+  Where `Memorable.Data.Image` holds information about the image's internal representation within memorable,
+  `DerivedMetadata` contains information about the image itself. When an image is imported into memorable,
+  `from_image/1` is called to extract metadata from EXIF tags, which gets stored in the memorable database for quick
+  access.
+
+  ## Fields
+  - `image_id`: The [ID](`t:Memorable.Util.id/0`) of the `Memorable.Data.Image` this metadata is associated with.
+  - `file_hash`: A SHA256 hash of the image file this metadata was derived from. This is used to ensure that the
+    metadata stored in the table is up to date, and matches the image on disk.
+
+  The following fields are retrieved from EXIF metadata stored in the image, and may be `nil` if the associated tags are
+  not present on the image:
+  - `original_datetime`: A `NaiveDateTime` representing when the image was taken.
+  - `lens_model`: The lens used to take the photo.
+  - `body_model`: The camera body used to take the photo.
+  - `focal_length`: The focal length the image was taken at, in millimetres.
+  - `aperture`: The aperture the image was taken at, represented as an f-number.
+  - `exposure_time`: The duration of time the image was exposed for, in seconds expressed as a rational (eg. "1/1250").
+  - `iso`: The ISO sensitivity the image was taken at.
+  """
+  @moduledoc since: "1.0.0"
+  alias Memorable.Data.Image.DerivedMetadata
+  alias Memorable.Data.Image.DerivedMetadata
   alias Memorable.Data.Image
 
   # `image_id` is 1:1 with an Image `id`
@@ -54,6 +107,18 @@ defmodule Memorable.Data.Image.DerivedMetadata do
           iso: integer()
         }
 
+  @doc """
+  Reads and parses metadata for a `Memorable.Data.Image`.
+
+  EXIF tags from an image file are retrieved with `Memorable.Data.Image.read_metadata/1`, and then parsed into the
+  format described above.
+
+  Returns:
+  - `{:ok, metadata}`: When metadata was successfully read and parsed from the image.
+  - `{:error, {:read_file, error}}`: When an error occured reading the image file from disk.
+  - `{:error, {:read_metadata, error}}`: When an error occurred while extracting EXIF tags from the image file.
+  """
+  @doc since: "1.0.0"
   @spec from_image(Image.t()) :: {:ok, t()} | {:error, any()}
   def from_image(%Image{id: image_id, path: path} = image) do
     with {:read_file, {:ok, data}} <- {:read_file, File.read(path)},
@@ -79,13 +144,16 @@ defmodule Memorable.Data.Image.DerivedMetadata do
     end
   end
 
+  # Parses the `DateTimeOriginal` field in EXIF into a `NaiveDateTime`.
   @spec original_datetime(Image.metadata()) :: NaiveDateTime.t() | nil
   defp original_datetime(metadata) do
     with result when result != nil <- Map.get(metadata, "DateTimeOriginal") do
       NaiveDateTime.from_iso8601!(result)
     end
   end
 
+  # Parses the `FocalLength` field in EXIF into a float, discarding the unit measurement.
+  # Currently assumes `exiftool` always returns focal length in millimetres, and fails if it doesn't.
   @spec focal_length(Image.metadata()) :: float() | nil
   defp focal_length(metadata) do
     with result when result != nil <- Map.get(metadata, "FocalLength") do