From e7f14dfd35598a736cbaf35b1cf374e0befed100 Mon Sep 17 00:00:00 2001
From: ArthurErlich <a.erlich@live.de>
Date: Sun, 12 Jul 2026 12:27:42 +0200
Subject: [PATCH] chore(doc): documentet all public methods

---
 src/Service/ContributionStore.php | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/src/Service/ContributionStore.php b/src/Service/ContributionStore.php
index c12a32f..7c8fd77 100644
--- a/src/Service/ContributionStore.php
+++ b/src/Service/ContributionStore.php
@@ -13,6 +13,9 @@ class ContributionStore
     private PDO $pdo;
     private const int DAY_IN_SECONDS = 86400;
 
+    /**
+     * Opens (creating if needed) the SQLite store at $dbPath and ensures the schema exists.
+     */
     public function __construct(
         private readonly string $dbPath = "%kernel.project_dir%/var/data/contributions.db",
         private readonly ?int $retentionDays = null,
@@ -38,6 +41,9 @@ class ContributionStore
         ');
     }
 
+    /**
+     * Inserts a contribution count, overwriting any existing count for the same provider/date.
+     */
     public function add(string $provider, int $unixtime, int $count): void
     {
         $stmt = $this->pdo->prepare('
@@ -48,6 +54,9 @@ class ContributionStore
         $stmt->execute([$provider, $unixtime, $count]);
     }
 
+    /**
+     * Deletes the contribution row for the given provider/date, if any.
+     */
     public function remove(string $provider, int $unixtime): void
     {
         $stmt = $this->pdo->prepare('
@@ -58,6 +67,8 @@ class ContributionStore
     }
 
     /**
+     * Upserts a batch of date => count pairs for a provider via repeated add() calls.
+     *
      * @param array<int, int> $dateCounts unix timestamp => count
      */
     public function merge(string $provider, array $dateCounts): void
@@ -67,6 +78,9 @@ class ContributionStore
         }
     }
 
+    /**
+     * Returns the most recent stored unix timestamp for a provider, or null if it has no rows.
+     */
     public function latestDate(string $provider): ?int
     {
         $stmt = $this->pdo->prepare('SELECT MAX(date) FROM contributions WHERE provider = ?');
@@ -76,6 +90,9 @@ class ContributionStore
         return $result !== null ? (int) $result : null;
     }
 
+    /**
+     * Returns all stored contributions for a provider, optionally limited to the last $sinceDays days.
+     */
     public function all(string $provider, ?int $sinceDays = null): ContributionCollection
     {
         $sql = 'SELECT provider, date, count FROM contributions WHERE provider = ?';
@@ -90,13 +107,16 @@ class ContributionStore
         $stmt->execute($params);
 
         $contributions = array_map(
-            static fn (array $row): Contribution => new Contribution($row['provider'], (int) $row['date'], (int) $row['count']),
+            static fn(array $row): Contribution => new Contribution($row['provider'], (int) $row['date'], (int) $row['count']),
             $stmt->fetchAll(PDO::FETCH_ASSOC),
         );
 
         return new ContributionCollection(...$contributions);
     }
 
+    /**
+     * Deletes rows older than the configured retention window; a no-op if retention is unset or 0.
+     */
     public function prune(): void
     {
         if ($this->retentionDays === null || $this->retentionDays === 0) {