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_web/auth.ex

@@ -5,10 +5,12 @@ defmodule MusicLibraryWeb.Auth do
   import Phoenix.Controller, only: [redirect: 2]
   import Plug.Conn
 
+  @spec correct_login_password?(String.t()) :: boolean()
   def correct_login_password?(password) do
     Plug.Crypto.secure_compare(login_password(), password)
   end
 
+  @spec require_api_token(Plug.Conn.t(), keyword()) :: Plug.Conn.t()
   def require_api_token(conn, _opts) do
     with ["Bearer " <> token] <- get_req_header(conn, "authorization"),
          true <- Plug.Crypto.secure_compare(api_token(), token) do
@@ -31,6 +33,7 @@ defmodule MusicLibraryWeb.Auth do
     |> Keyword.fetch!(:api_token)
   end
 
+  @spec require_logged_in(Plug.Conn.t(), keyword()) :: Plug.Conn.t()
   def require_logged_in(conn, _opts) do
     if get_session(conn, :logged_in) do
       conn

lib/music_library_web/components/pagination.ex

@@ -162,6 +162,7 @@ defmodule MusicLibraryWeb.Components.Pagination do
     """
   end
 
+  @spec page_to_offset(pos_integer(), pos_integer()) :: non_neg_integer()
   def page_to_offset(page, per_page) do
     (page - 1) * per_page
   end

lib/music_library_web/duration.ex

@@ -21,6 +21,7 @@ defmodule MusicLibraryWeb.Duration do
       "0:00"
 
   """
+  @spec format_duration(non_neg_integer()) :: String.t()
   def format_duration(milliseconds) do
     milliseconds
     |> System.convert_time_unit(:millisecond, :second)

lib/music_library_web/error_messages.ex

@@ -9,6 +9,8 @@ defmodule MusicLibraryWeb.ErrorMessages do
 
   use Gettext, backend: MusicLibraryWeb.Gettext
 
+  @spec friendly_message(term()) :: String.t()
+
   # App error atoms
   def friendly_message(:cover_not_available), do: gettext("cover art is not available")
   def friendly_message(:no_duration), do: gettext("release has no track duration information")

lib/music_library_web/live_helpers/params.ex

@@ -1,6 +1,7 @@
 defmodule MusicLibraryWeb.LiveHelpers.Params do
   @pagination Application.compile_env!(:music_library, :pagination)
 
+  @spec parse_page(String.t() | nil | term()) :: pos_integer()
   def parse_page(nil), do: 1
 
   def parse_page(page) when is_binary(page) do
@@ -12,6 +13,8 @@ defmodule MusicLibraryWeb.LiveHelpers.Params do
 
   def parse_page(_), do: 1
 
+  @spec parse_page_size(String.t() | nil | term(), [pos_integer()] | nil, pos_integer()) ::
+          pos_integer()
   def parse_page_size(nil, _allowed, default), do: default
 
   def parse_page_size(page_size, allowed, default) when is_binary(page_size) do
@@ -26,6 +29,7 @@ defmodule MusicLibraryWeb.LiveHelpers.Params do
 
   def parse_page_size(_, _allowed, default), do: default
 
+  @spec merge_pagination(map(), map(), non_neg_integer(), keyword()) :: map()
   def merge_pagination(params, url_params, total_entries, opts \\ []) do
     allowed = Keyword.get(opts, :allowed_page_sizes)
     default_page_size = params[:page_size] || @pagination[:default_page_size]
@@ -39,14 +43,18 @@ defmodule MusicLibraryWeb.LiveHelpers.Params do
     |> Map.put(:total_entries, total_entries)
   end
 
+  @spec merge_query(map(), String.t() | nil) :: map()
   def merge_query(params, query) do
     Map.put(params, :query, query)
   end
 
+  @spec merge_order(map(), atom()) :: map()
   def merge_order(params, order) do
     Map.put(params, :order, order)
   end
 
+  @spec apply_fallback_index(Phoenix.LiveView.Socket.t(), map(), atom(), function()) ::
+          Phoenix.LiveView.Socket.t()
   def apply_fallback_index(socket, params, stream_key, apply_action_fn) do
     if get_in(socket.assigns, [:streams, stream_key]) == nil do
       apply_action_fn.(socket, :index, params)

lib/music_library_web/markdown.ex

@@ -12,6 +12,7 @@ defmodule MusicLibraryWeb.Markdown do
 
   Double square brackets are converted to search links before the markdown is processed.
   """
+  @spec to_html(String.t() | nil) :: String.t()
   def to_html(markdown_text) when is_binary(markdown_text) do
     markdown_text
     |> process_double_bracket_links()
@@ -41,6 +42,7 @@ defmodule MusicLibraryWeb.Markdown do
       iex> MusicLibraryWeb.Markdown.process_double_bracket_links(~s|[[genre:"psychedelic rock"]]|)
       ~s|[psychedelic rock](/collection?query=genre%3A%22psychedelic+rock%22)|
   """
+  @spec process_double_bracket_links(String.t()) :: String.t()
   def process_double_bracket_links(text) do
     ~r/\[\[([^\]]+)\]\]/
     |> Regex.replace(text, fn _match, content ->