From bc72ab7e7f6b548214966a1925ffafbab9ee45e5 Mon Sep 17 00:00:00 2001 From: Claudio Ortolina Date: Thu, 3 Apr 2025 09:44:42 +0100 Subject: [PATCH] Document Last.fm refresh module --- lib/last_fm/refresh.ex | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/lib/last_fm/refresh.ex b/lib/last_fm/refresh.ex index 79003c4c..215f6a0b 100644 --- a/lib/last_fm/refresh.ex +++ b/lib/last_fm/refresh.ex @@ -1,4 +1,38 @@ defmodule LastFm.Refresh do + @moduledoc """ + A GenServer that manages periodic refreshing of Last.fm scrobbled tracks. + + This module is responsible for: + - Fetching recent tracks from Last.fm at configurable intervals + - Updating an in-memory feed with the latest tracks + - Supporting both automatic and manual refresh modes + + ## Configuration + + The server accepts a `LastFm.Config` struct with the following options: + - `auto_refresh`: When true, automatically starts refreshing on init + - `refresh_interval`: Time in milliseconds between refresh attempts + + ## Operation Modes + + 1. Automatic Mode (`auto_refresh: true`): + - Starts refreshing immediately on initialization + - Continues to refresh at the configured interval + - Handles failures gracefully by continuing to retry + + 2. Manual Mode (`auto_refresh: false`): + - Server remains dormant on initialization + - Refreshes only occur via explicit `refresh/0` calls + - Useful for testing or controlled refresh scenarios + + ## Usage + + # Manual refresh + LastFm.Refresh.refresh() + + The module uses `LastFm.Feed` to store and broadcast track updates to subscribers. + """ + use GenServer require Logger