First pass at uniformed types, specs and docs

- spec public functions (skipping controllers, views, live views and
components)
- use types instead of explanations in docs
- remove redundant docs
- fix typos

lib/music_brainz/release.ex

@@ -24,33 +24,73 @@ defmodule MusicBrainz.Release do
     :media
   ]
 
+  @type t :: %__MODULE__{
+          id: String.t(),
+          title: String.t(),
+          disambiguation: String.t() | nil,
+          packaging: String.t() | nil,
+          artists: [Artist.t()],
+          date: String.t() | nil,
+          barcode: String.t() | nil,
+          catalog_number: String.t(),
+          country: String.t() | nil,
+          media: [Medium.t()]
+        }
+
   defmodule Artist do
     @enforce_keys [:id, :name, :sort_name]
     defstruct [:id, :name, :sort_name]
+
+    @type t :: %__MODULE__{
+            id: String.t(),
+            name: String.t(),
+            sort_name: String.t()
+          }
   end
 
   defmodule Medium do
     @enforce_keys [:title, :format, :number, :track_count, :tracks]
     defstruct [:title, :format, :number, :track_count, :tracks]
+
+    @type t :: %__MODULE__{
+            title: String.t() | nil,
+            format: String.t() | nil,
+            number: non_neg_integer(),
+            track_count: non_neg_integer(),
+            tracks: [MusicBrainz.Release.Track.t()]
+          }
   end
 
   defmodule Track do
     @enforce_keys [:id, :title, :artists, :length, :number, :position]
     defstruct [:id, :title, :artists, :length, :number, :position]
+
+    @type t :: %__MODULE__{
+            id: String.t(),
+            title: String.t(),
+            artists: [MusicBrainz.Release.Artist.t()],
+            length: non_neg_integer() | nil,
+            number: String.t(),
+            position: non_neg_integer()
+          }
   end
 
+  @spec media_count(t()) :: non_neg_integer()
   def media_count(release) do
     Enum.count(release.media)
   end
 
+  @spec get_medium(t(), non_neg_integer()) :: Medium.t() | nil
   def get_medium(release, medium_number) do
     Enum.find(release.media, fn m -> m.number == medium_number end)
   end
 
+  @spec medium_duration(Medium.t()) :: non_neg_integer()
   def medium_duration(medium) do
     Enum.sum_by(medium.tracks, fn track -> track.length || 0 end)
   end
 
+  @spec medium_tracks(t(), non_neg_integer()) :: [Track.t()]
   def medium_tracks(release, medium_number) do
     case Enum.find(release.media, fn m -> m.number == medium_number end) do
       nil -> []
@@ -58,14 +98,17 @@ defmodule MusicBrainz.Release do
     end
   end
 
+  @spec release_duration(t()) :: non_neg_integer()
   def release_duration(release) do
     Enum.sum_by(release.media, fn medium -> medium_duration(medium) end)
   end
 
+  @spec tracks(t()) :: [Track.t()]
   def tracks(release) do
     Enum.flat_map(release.media, fn medium -> medium.tracks end)
   end
 
+  @spec from_api_response(map()) :: t()
   def from_api_response(r) do
     %__MODULE__{
       id: r["id"],
@@ -81,6 +124,7 @@ defmodule MusicBrainz.Release do
     }
   end
 
+  @spec thumb_url(t()) :: String.t()
   def thumb_url(release) do
     "https://coverartarchive.org/release/#{release.id}/front-250"
   end