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_library/artists/artist.ex

@@ -11,6 +11,9 @@ defmodule MusicLibrary.Artists.Artist do
     field :joinphrase, :string, default: ""
   end
 
+  @type t :: %__MODULE__{}
+
+  @spec changeset(t() | Ecto.Changeset.t(), map()) :: Ecto.Changeset.t()
   def changeset(artist, attrs) do
     artist
     |> cast(attrs, [:name, :sort_name, :disambiguation, :joinphrase, :musicbrainz_id])

lib/music_library/artists/artist_info.ex

@@ -19,6 +19,9 @@ defmodule MusicLibrary.Artists.ArtistInfo do
     timestamps(type: :utc_datetime)
   end
 
+  @type t :: %__MODULE__{}
+
+  @spec changeset(t() | Ecto.Changeset.t(), map()) :: Ecto.Changeset.t()
   def changeset(artist_info, attrs) do
     artist_info
     |> cast(attrs, [
@@ -32,6 +35,7 @@ defmodule MusicLibrary.Artists.ArtistInfo do
     |> validate_required([:musicbrainz_data])
   end
 
+  @spec country(t()) :: %{name: String.t(), code: String.t()}
   def country(artist_info) do
     %{"area" => area} =
       artist_info.musicbrainz_data
@@ -45,6 +49,9 @@ defmodule MusicLibrary.Artists.ArtistInfo do
     %{name: area["name"] || "World", code: country_code || "XW"}
   end
 
+  @spec extract_image(t()) ::
+          {:ok, %{url: String.t(), width: integer()}}
+          | {:error, :no_discogs_data | :image_not_found}
   def extract_image(artist_info) when is_nil(artist_info.discogs_data) do
     {:error, :no_discogs_data}
   end
@@ -71,9 +78,11 @@ defmodule MusicLibrary.Artists.ArtistInfo do
     "ProgArchives" => "progarchives.com"
   }
 
+  @spec external_links(t()) :: [map()]
   def external_links(artist_info),
     do: ExternalLink.external_links(artist_info.musicbrainz_data, @external_link_patterns)
 
+  @spec discogs_id(t()) :: integer() | nil
   def discogs_id(artist_info) do
     case artist_info.discogs_data do
       %{"id" => discogs_id} -> discogs_id
@@ -81,6 +90,7 @@ defmodule MusicLibrary.Artists.ArtistInfo do
     end
   end
 
+  @spec wikidata_id(t()) :: String.t() | nil
   def wikidata_id(artist_info) do
     relations = get_in(artist_info.musicbrainz_data, ["relations"]) || []
 
@@ -93,27 +103,33 @@ defmodule MusicLibrary.Artists.ArtistInfo do
     end)
   end
 
+  @spec wikipedia_bio(t()) :: String.t() | nil
   def wikipedia_bio(artist_info) do
     get_in(artist_info.wikipedia_data, ["intro_html"]) ||
       get_in(artist_info.wikipedia_data, ["extract_html"])
   end
 
+  @spec wikipedia_summary(t()) :: String.t() | nil
   def wikipedia_summary(artist_info) do
     get_in(artist_info.wikipedia_data, ["extract"])
   end
 
+  @spec wikipedia_url(t()) :: String.t() | nil
   def wikipedia_url(artist_info) do
     get_in(artist_info.wikipedia_data, ["content_urls", "desktop", "page"])
   end
 
+  @spec wikipedia_description(t()) :: String.t() | nil
   def wikipedia_description(artist_info) do
     get_in(artist_info.wikipedia_data, ["description"])
   end
 
+  @spec lastfm_tags(t()) :: [map()]
   def lastfm_tags(artist_info) do
     get_in(artist_info.lastfm_data, ["tags"]) || []
   end
 
+  @spec lastfm_similar_artists(t()) :: [map()]
   def lastfm_similar_artists(artist_info) do
     get_in(artist_info.lastfm_data, ["similar_artists"]) || []
   end

lib/music_library/artists/batch.ex

@@ -5,24 +5,28 @@ defmodule MusicLibrary.Artists.Batch do
   alias MusicLibrary.Artists.ArtistInfo
   alias MusicLibrary.Batch
 
+  @spec refresh_musicbrainz_data() :: {:ok, [String.t()]}
   def refresh_musicbrainz_data do
     Batch.run_on_all(from(r in ArtistInfo), "artist_info", fn artist_info ->
       Artists.refresh_musicbrainz_data_async(artist_info)
     end)
   end
 
+  @spec refresh_discogs_data() :: {:ok, [String.t()]}
   def refresh_discogs_data do
     Batch.run_on_all(from(r in ArtistInfo), "artist_info", fn artist_info ->
       Artists.refresh_discogs_data_async(artist_info)
     end)
   end
 
+  @spec refresh_wikipedia_data() :: {:ok, [String.t()]}
   def refresh_wikipedia_data do
     Batch.run_on_all(from(r in ArtistInfo), "artist_info", fn artist_info ->
       Artists.refresh_wikipedia_data_async(artist_info)
     end)
   end
 
+  @spec refresh_lastfm_data() :: {:ok, [String.t()]}
   def refresh_lastfm_data do
     Batch.run_on_all(from(r in ArtistInfo), "artist_info", fn artist_info ->
       Artists.fetch_lastfm_data_async(artist_info.id)