From f36d8e73048e561cdf88e8f32d26dfd1aec32159 Mon Sep 17 00:00:00 2001
From: Aeonoi <dzhou527@gmail.com>
Date: Sun, 20 Oct 2024 11:48:10 -0400
Subject: [PATCH] docs(lib): add JSDoc to useful-functions

working on #65
---
 lib/useful-functions.ts | 124 ++++++++++++++++++++++++++--------------
 1 file changed, 82 insertions(+), 42 deletions(-)

diff --git a/lib/useful-functions.ts b/lib/useful-functions.ts
index 4c18f12..d40ec4e 100644
--- a/lib/useful-functions.ts
+++ b/lib/useful-functions.ts
@@ -1,7 +1,47 @@
 // ALl functions that should not be async
 import type { IFocus } from "@/models/focuses";
 
-export function shuffleArray<T>(array: T[]) {
+/**
+ * Rank Name (String) : Maximum Points For Rank (Number)
+ */
+export const rankPoints = new Map<string, number | undefined>([
+  ["Iron", 1000],
+  ["Bronze-5", 2800],
+  ["Bronze-4", 4600],
+  ["Bronze-3", 6400],
+  ["Bronze-2", 8200],
+  ["Bronze-1", 10000],
+  ["Silver-5", 12000],
+  ["Silver-4", 14000],
+  ["Silver-3", 16000],
+  ["Silver-2", 18000],
+  ["Silver-1", 20000],
+  ["Gold-5", 26000],
+  ["Gold-4", 32000],
+  ["Gold-3", 38000],
+  ["Gold-2", 44000],
+  ["Gold-1", 50000],
+  ["Platinum-5", 60000],
+  ["Platinum-4", 70000],
+  ["Platinum-3", 80000],
+  ["Platinum-2", 90000],
+  ["Platinum-1", 100000],
+  ["Diamond-5", 120000],
+  ["Diamond-4", 140000],
+  ["Diamond-3", 160000],
+  ["Diamond-2", 180000],
+  ["Diamond-1", 200000],
+  ["Masters", 1000000],
+  ["Mythical", undefined],
+]);
+
+/**
+ * Shuffles array into random order
+ *
+ * @param {T} array - The array to be shuffled
+ * @returns {T[]} Returns the shuffled array
+ */
+export function shuffleArray<T>(array: T[]): T[] {
   let j: number;
   let i: number;
   let x: T;
@@ -16,9 +56,9 @@ export function shuffleArray<T>(array: T[]) {
 
 /**
  * Compares two dates and determines if they are consecutive or back to back to each other (compares day, hours are neglible)
- * @param date1 - The first date
- * @param date2 - The second date
- * @returns Returns the difference (in days) between the two dates
+ * @param {Date} date1 - The first date
+ * @param {Date} date2 - The second date
+ * @returns {number} Returns the difference (in days) between the two dates
  */
 export function compareTwoDates(date1: Date, date2: Date): number {
   // set to use UTC
@@ -35,23 +75,43 @@ export function compareTwoDates(date1: Date, date2: Date): number {
   return differenceInDays;
 }
 
+/**
+ * @param {number} time - The number of seconds to be converted
+ * @returns {number} Time in minutes
+ */
 export function convertSecondsToMinutes(time: number): number {
   return time / 60;
 }
 
+/**
+ * @param {number} time - The number of milliseconds to be converted
+ * @returns {number} Time in minutes
+ */
 export function convertMsToMinutes(time: number): number {
   return time / 60000;
 }
 
+/**
+ * @param {number} time - The number of milliseconds to be converted
+ * @returns {number} Time in seconds
+ */
 export function convertMsToSeconds(time: number): number {
   return time / 1000;
 }
 
-export function convertMinutesToHours(time: number) {
+/**
+ * @param {number} time - The number of minutes to be converted
+ * @returns {number} Time in hours
+ */
+export function convertMinutesToHours(time: number): number {
   return time / 60;
 }
 
-export function getGroupedTotalFocusTime(arr: IFocus[]) {
+/**
+ * @param {IFocus[]} arr - The array of type IFocus
+ * @returns {number} Total time, that is, the sum arr
+ */
+export function getGroupedTotalFocusTime(arr: IFocus[]): number {
   let ret = 0;
   arr.map((focus) => {
     ret += focus.time;
@@ -60,7 +120,12 @@ export function getGroupedTotalFocusTime(arr: IFocus[]) {
   return ret;
 }
 
-export function getReadableDate(oldDate: Date | undefined) {
+/**
+ * Converts a JavaScript Date object to string representation
+ *
+ * @returns {string | undefined} Readable string representation of a JavaScript Date object
+ */
+export function getReadableDate(oldDate: Date | undefined): string | undefined {
   if (!oldDate) {
     return;
   }
@@ -72,8 +137,11 @@ export function getReadableDate(oldDate: Date | undefined) {
   return `${month}/${day}/${year}`;
 }
 
+/**
+ * Print debugging :)
+ */
 // biome-ignore lint/suspicious/noExplicitAny: only for debugging
-export function debug_print(args: any[] = []) {
+export function debug_print(args: any[] = []): void {
   console.log("----------------------------------------------------");
   console.log("DEBUG HERE");
   args.map((arg, index) => {
@@ -83,8 +151,12 @@ export function debug_print(args: any[] = []) {
 }
 
 /**
- * @returns A string representation of the current tier (Rank-Division)
- * or optionally, the next tier. Will return undefined if looking for next rank and current rank is Mythical
+ *
+ * Gets rank given the number of points
+ *
+ * @param {number} currentPoints - The number of points to check the rank of
+ * @param {boolean} [ next ] - Flag to determine if checking for next tier
+ * @returns {string | undefined} A string representation of the current tier (Rank-Division) or optionally, the next tier. Will return undefined if looking for next rank and current rank is Mythical
  */
 export function getTier(
   currentPoints: number,
@@ -194,35 +266,3 @@ export function getTier(
       return "Iron";
   }
 }
-
-// Rank Name (String) : Maximum Points For Rank (Number)
-export const rankPoints = new Map([
-  ["Iron", 1000],
-  ["Bronze-5", 2800],
-  ["Bronze-4", 4600],
-  ["Bronze-3", 6400],
-  ["Bronze-2", 8200],
-  ["Bronze-1", 10000],
-  ["Silver-5", 12000],
-  ["Silver-4", 14000],
-  ["Silver-3", 16000],
-  ["Silver-2", 18000],
-  ["Silver-1", 20000],
-  ["Gold-5", 26000],
-  ["Gold-4", 32000],
-  ["Gold-3", 38000],
-  ["Gold-2", 44000],
-  ["Gold-1", 50000],
-  ["Platinum-5", 60000],
-  ["Platinum-4", 70000],
-  ["Platinum-3", 80000],
-  ["Platinum-2", 90000],
-  ["Platinum-1", 100000],
-  ["Diamond-5", 120000],
-  ["Diamond-4", 140000],
-  ["Diamond-3", 160000],
-  ["Diamond-2", 180000],
-  ["Diamond-1", 200000],
-  ["Masters", 1000000],
-  ["Mythical", undefined],
-]);