From 6a4cb306ed82ed3e7e6ea0d67f0b7333433f06bf Mon Sep 17 00:00:00 2001
From: Viktor Varenik <38311102+kotleni@users.noreply.github.com>
Date: Sun, 5 Nov 2023 21:04:17 +0000
Subject: [PATCH] refactor: updated docs in TimerSessionRepository

---
 .../repositories/TimerSessionRepository.kt    | 33 ++++++++++++++++---
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/core/src/main/kotlin/io/timemates/backend/timers/repositories/TimerSessionRepository.kt b/core/src/main/kotlin/io/timemates/backend/timers/repositories/TimerSessionRepository.kt
index 350dac40..9b3a3a06 100644
--- a/core/src/main/kotlin/io/timemates/backend/timers/repositories/TimerSessionRepository.kt
+++ b/core/src/main/kotlin/io/timemates/backend/timers/repositories/TimerSessionRepository.kt
@@ -19,25 +19,34 @@ interface TimerSessionRepository : TimersStateMachine, Repository {
      *
      * @param timerId The id of the timer.
      * @param userId The id of the user that joins.
+     * @param joinTime The Unix time at which the user joined the timer session.
      */
     suspend fun addUser(timerId: TimerId, userId: UserId, joinTime: UnixTime)
 
     /**
      * Removes user from session in given timer with [timerId].
      *
-     * @param timerId from which user will be removed
-     * @param userId which user will be removed
-     * @param onEmpty invokes if in session no user left
+     * @param timerId From which user will be removed.
+     * @param userId Which user will be removed.
      */
     suspend fun removeUser(timerId: TimerId, userId: UserId)
 
     /**
+     * Get a id of the timer of current session.
+     * 
+     * @param userId The id of the user that joins.
+     * @param lastActiveTime The Unix time at which the user joined the timer session.
+     * 
      * @return [TimerId] of a session where's the user joined or `null`.
      */
     suspend fun getTimerIdOfCurrentSession(userId: UserId, lastActiveTime: UnixTime): TimerId?
 
     /**
      * Gets members of a session.
+     * 
+     * @param timerId The id of the timer.
+     * @param pageToken A page token that identifies a specific page.
+     * @param lastActiveTime The Unix time at which the user joined the timer session.
      */
     suspend fun getMembers(
         timerId: TimerId,
@@ -45,12 +54,20 @@ interface TimerSessionRepository : TimersStateMachine, Repository {
         lastActiveTime: UnixTime,
     ): Page<UserId>
 
+    /**
+     * Get count of members in a session.
+     * 
+     * @param timerId The id of the timer.
+     * @param activeAfterTime The Unix time at which the user joined the timer session.
+     */
     suspend fun getMembersCount(timerId: TimerId, activeAfterTime: UnixTime): Count
 
     /**
      * Sets confirmation requirement of a timer to users that are currently active. We
      * do not apply it to all users as users that joined after should be automatically marked as
      * confirmed.
+     * 
+     * @param timerId The id of the timer.
      */
     suspend fun setActiveUsersConfirmationRequirement(timerId: TimerId)
 
@@ -59,6 +76,7 @@ interface TimerSessionRepository : TimersStateMachine, Repository {
      *
      * @param timerId The id of the timer.
      * @param userId The id of the user that confirms his attendance.
+     * @param confirmationTime The Unix time of moment when user ben confirmed.
      *
      * @return [Boolean] whether there's any other user left to confirm his attendance.
      */
@@ -66,20 +84,25 @@ interface TimerSessionRepository : TimersStateMachine, Repository {
 
     /**
      * Removes all users that didn't have activity after given [afterTime].
-     * @param afterTime last active time after which all users will be removed.
+     * 
+     * @param afterTime The Unix time of last active time after which all users will be removed.
      */
     suspend fun removeInactiveUsers(afterTime: UnixTime)
 
     /**
      * Removes all users that haven't confirmed his attendance.
      *
-     * @param timerId timer from which we're going to remove users that didn't confirmed
+     * @param timerId The timer from which we're going to remove users that didn't confirmed
      * their attendance.
      */
     suspend fun removeNotConfirmedUsers(timerId: TimerId)
 
     /**
      * Updates last user activity time in session. It should be done every 5-10 minutes by the client.
+     * 
+     * @param timerId The id of the timer.
+     * @param userId The id of the user that confirms his attendance.
+     * @param time The Unix time of last user activity.
      */
     suspend fun updateLastActivityTime(timerId: TimerId, userId: UserId, time: UnixTime)
 }