From 29fc568200b1aaaf2fab84064d8c92fff8a9aaff Mon Sep 17 00:00:00 2001
From: Martin Unger <martin.unger@planet-earth.at>
Date: Mon, 1 Jan 2024 23:12:53 +0100
Subject: [PATCH] add docs for time control and timeout service

---
 packages/server/src/time-control.ts | 28 ++++++++++++++++++++++++++++
 packages/server/src/timeout.ts      | 15 +++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/packages/server/src/time-control.ts b/packages/server/src/time-control.ts
index 52146d57..5b9cb21d 100644
--- a/packages/server/src/time-control.ts
+++ b/packages/server/src/time-control.ts
@@ -10,6 +10,10 @@ import { AbstractGame, GameResponse } from "@ogfcommunity/variants-shared";
 import { TimeoutService } from './timeout';
 import { getTimeoutService } from './index';
 
+/**
+ * Validates whether game_config has type and 
+ * properties for being a config with time control
+ */
 export function HasTimeControlConfig(
   game_config: unknown,
 ): game_config is IConfigWithTimeControl {
@@ -20,6 +24,10 @@ export function HasTimeControlConfig(
   );
 }
 
+/**
+ * Validates whether time_control_config has type and 
+ * properties for being a time control config
+ */
 export function ValidateTimeControlConfig(
   time_control_config: unknown,
 ): time_control_config is ITimeControlConfig {
@@ -31,6 +39,10 @@ export function ValidateTimeControlConfig(
   );
 }
 
+/**
+ * Validates whether time_control has type and 
+ * properties for being a basic time control data object
+ */
 export function ValidateTimeControlBase(
   time_control: unknown,
 ): time_control is ITimeControlBase {
@@ -42,6 +54,10 @@ export function ValidateTimeControlBase(
   );
 }
 
+/**
+ * Returns the initial state of a time control data object
+ * for a new game, if it has time control at all
+ */
 export function GetInitialTimeControl(variant: string, config: object): ITimeControlBase | null {
   if (!HasTimeControlConfig(config)) return null;
 
@@ -51,8 +67,16 @@ export function GetInitialTimeControl(variant: string, config: object): ITimeCon
 
 // validation of the config should happen before this is called
 export interface ITimeHandler {
+
+  /**
+   * Returns the initial state of a time control data object
+   * that this handler works with
+   */
   initialState(variant: string, config: IConfigWithTimeControl): ITimeControlBase;
 
+  /**
+   * transition for the time control data when a move is played
+   */
   handleMove(
     game: GameResponse,
     game_obj: AbstractGame<unknown, unknown>,
@@ -60,6 +84,10 @@ export interface ITimeHandler {
     move: string,
   ): ITimeControlBase;
 
+  /**
+   * Returns the time in milliseconds until this player
+   * times out, provided no moves are played
+   */
   getMsUntilTimeout(game: GameResponse, playerNr: number): number;
 }
 
diff --git a/packages/server/src/timeout.ts b/packages/server/src/timeout.ts
index 243bef68..6c5d02ae 100644
--- a/packages/server/src/timeout.ts
+++ b/packages/server/src/timeout.ts
@@ -20,6 +20,9 @@ export class TimeoutService {
     constructor() {
     }
 
+    /**
+     * initializes timeout schedules
+     */
     public async initialize(): Promise<void> {
         // I would like to improve this by only querying unfinished games from db
         // but currently I think its not possible, because of the game result
@@ -51,6 +54,10 @@ export class TimeoutService {
         }
     }
 
+    /**
+     * stores a timeout-id or null for this player + game
+     * if an id was previously stored, the timeout is cleared
+     */
     private setPlayerTimeout(gameId: string, playerNr: number, timeout: ReturnType<typeof setTimeout> | null): void {
         let gameTimeouts = this.timeoutsByGame.get(gameId);
 
@@ -68,6 +75,9 @@ export class TimeoutService {
         gameTimeouts[playerNr] = timeout;
     }
 
+    /**
+     * clears the timeout-ids of this game
+     */
     public clearGameTimeouts(gameId: string): void {
         const gameTimeouts = this.timeoutsByGame.get(gameId)
 
@@ -81,6 +91,11 @@ export class TimeoutService {
         this.setPlayerTimeout(gameId, playerNr, null);
     }
 
+    /**
+     * schedules a timeout for this player + game
+     * timeout is resolved by adding a timeout move
+     * and applying the time control handler again
+     */
     public scheduleTimeout(gameId: string, playerNr: number, inTimeMs: number): void {
         const timeoutResolver = async () => {
             const game = await getGame(gameId)