Merge pull request #393 from cornell-dti/add-utils-documentation

Add utils documentation

Author: ggsawatyanon

frontend/src/utils/adminTool.ts

@@ -1,4 +1,16 @@
 import { admins } from '../constants/HomeConsts';
+
+/**
+ * isAdmin – Checks whether a given user is an admin.
+ *
+ * @remarks
+ * This function verifies if the user provided has an email that matches one of the predefined admin emails.
+ *
+ * @param {firebase.User | null} user – The Firebase user object to check. Can be `null`.
+ *
+ * @returns {boolean} – `true` if the user is an admin, otherwise `false`.
+ */
+
 export const isAdmin = (user: firebase.User | null) => {
   if (user && typeof user?.email === 'string' && admins.includes(user?.email)) return true;
   return false;

frontend/src/utils/average.ts

@@ -1,5 +1,18 @@
 import { ReviewWithId } from '../../../common/types/db-types';
 
+/**
+ * getAverageRating – Calculates the average overall rating from an array of reviews.
+ *
+ * @remarks
+ * This function sums the `overallRating` values of all reviews where the rating is greater than 0
+ * and divides the sum by the total number of reviews in the array. If all reviews have a rating of 0,
+ * the function returns 0.
+ *
+ * @param {ReviewWithId[]} reviewData – Array of ReviewWithId objects (reviews)
+ *
+ * @returns {number} – The average overall rating of the provided reviews.
+ */
+
 const getAverageRating = (reviewData: ReviewWithId[]) =>
   reviewData.reduce(
     (currSum, { overallRating }) => (overallRating > 0 ? currSum + overallRating : currSum),

frontend/src/utils/call.ts

@@ -5,6 +5,19 @@ export type GetOptions<T> = {
   errorHandler?: () => void;
   body?: any;
 };
+/**
+ * get – Sends a GET request to the specified backend API endpoint.
+ *
+ * @remarks
+ * This function simplifies the process of making a GET request using Axios by only requiring the route as it will
+ * handle the callback, error console log, and error handling for you. This function doesn't return a value but will
+ * execute the callback function (if provided) with the response data if successful.
+ *
+ * @param {string} route – The API endpoint to send the GET request to.
+ * @param {GetOptions<T>} options – Optional parameters including: callback for handling the response, error handler
+ * for handling request failures, and an optional request body.
+ * @param {AxiosRequestConfig} inputConfig – Optional Axios configuration to customize the request.
+ */
 
 const get = <T>(route: string, options: GetOptions<T> = {}, inputConfig?: AxiosRequestConfig) => {
   const { callback, errorHandler, body } = options;