Added comments to TypeScript API, merge

frontend/src/API/API.ts

@@ -7,52 +7,102 @@ import {
   WeeklyReport,
 } from "../Types/goTypes";
 
-// This type of pattern should be hard to misuse
+/**
+ * Response object returned by API methods.
+ */
 export interface APIResponse<T> {
+  /** Indicates whether the API call was successful */
   success: boolean;
+  /** Optional message providing additional information or error description */
   message?: string;
+  /** Optional data returned by the API method */
   data?: T;
 }
 
-// Note that all protected routes also require a token
-// Defines all the methods that an instance of the API must implement
+/**
+ * Interface defining methods that an instance of the API must implement.
+ */
 interface API {
-  /** Register a new user */
+  /**
+   * Register a new user
+   * @param {NewUser} user The user object to be registered
+   * @returns {Promise<APIResponse<User>>} A promise containing the API response with the user data.
+   */
   registerUser(user: NewUser): Promise<APIResponse<User>>;
-  /** Remove a user */
+
+  /**
+   * Removes a user.
+   * @param {string} username The username of the user to be removed.
+   * @param {string} token The authentication token.
+   * @returns {Promise<APIResponse<User>>} A promise containing the API response with the removed user data.
+   */
   removeUser(username: string, token: string): Promise<APIResponse<User>>;
-  /** Check if user is project manager */
+
+  /**
+   * Check if user is project manager.
+   * @param {string} username The username of the user.
+   * @param {string} projectName The name of the project.
+   * @param {string} token The authentication token.
+   * @returns {Promise<APIResponse<boolean>>} A promise containing the API response indicating if the user is a project manager.
+   */
   checkIfProjectManager(
     username: string,
     projectName: string,
     token: string,
   ): Promise<APIResponse<boolean>>;
-  /** Login */
+
+  /** Logs in a user with the provided credentials.
+   * @param {NewUser} NewUser The user object containing username and password.
+   * @returns {Promise<APIResponse<string>>} A promise resolving to an API response with a token.
+   */
   login(NewUser: NewUser): Promise<APIResponse<string>>;
-  /** Renew the token */
+
+  /**
+   *  Renew the token
+   * @param {string} token The current authentication token.
+   * @returns {Promise<APIResponse<string>>} A promise resolving to an API response with a renewed token.
+   */
   renewToken(token: string): Promise<APIResponse<string>>;
+
   /** Promote user to admin */
-  /** Create a project */
+
+  /** Creates a new project.
+   * @param {NewProject} project The project object containing name and description.
+   * @param {string} token The authentication token.
+   * @returns {Promise<APIResponse<Project>>} A promise resolving to an API response with the created project.
+   */
   createProject(
     project: NewProject,
     token: string,
   ): Promise<APIResponse<Project>>;
-  /** Submit a weekly report */
+
+  /** Submits a weekly report
+   * @param {NewWeeklyReport} weeklyReport The weekly report object.
+   * @param {string} token The authentication token.
+   * @returns {Promise<APIResponse<NewWeeklyReport>>} A promise resolving to an API response with the submitted report.
+   */
   submitWeeklyReport(
-    project: NewWeeklyReport,
+    weeklyReport: NewWeeklyReport,
     token: string,
   ): Promise<APIResponse<NewWeeklyReport>>;
-  /**Gets a weekly report*/
+
+  /** Gets a weekly report for a specific user, project and week
+   * @param {string} username The username of the user.
+   * @param {string} projectName The name of the project.
+   * @param {string} week The week number.
+   * @param {string} token The authentication token.
+   * @returns {Promise<APIResponse<WeeklyReport>>} A promise resolving to an API response with the retrieved report.
+   */
   getWeeklyReport(
     username: string,
     projectName: string,
     week: string,
     token: string,
   ): Promise<APIResponse<WeeklyReport>>;
+
   /**
    * Returns all the weekly reports for a user in a particular project
    * The username is derived from the token
-   *
    * @param {string} projectName The name of the project
    * @param {string} token The token of the user
    * @returns {APIResponse<WeeklyReport[]>} A list of weekly reports
@@ -61,15 +111,27 @@ interface API {
     projectName: string,
     token: string,
   ): Promise<APIResponse<WeeklyReport[]>>;
-  /** Gets all the projects of a user*/
+
+  /** Gets all the projects of a user
+   * @param {string} token - The authentication token.
+   * @returns {Promise<APIResponse<Project[]>>} A promise containing the API response with the user's projects.
+   */
   getUserProjects(token: string): Promise<APIResponse<Project[]>>;
-  /** Gets a project from id*/
+
+  /** Gets a project by its id.
+   * @param {number} id The id of the project to retrieve.
+   * @returns {Promise<APIResponse<Project>>} A promise resolving to an API response containing the project data.
+   */
   getProject(id: number): Promise<APIResponse<Project>>;
-  /** Gets a project from id*/
+
+  /** Gets a list of all users.
+   * @param {string} token The authentication token of the requesting user.
+   * @returns {Promise<APIResponse<string[]>>} A promise resolving to an API response containing the list of users.
+   */
   getAllUsers(token: string): Promise<APIResponse<string[]>>;
 }
 
-// Export an instance of the API
+/** An instance of the API */
 export const api: API = {
   async registerUser(user: NewUser): Promise<APIResponse<User>> {
     try {
@@ -336,7 +398,6 @@ export const api: API = {
     }
   },
 
-  // Gets a projet by id, currently untested since we have no javascript-based tests
   async getProject(id: number): Promise<APIResponse<Project>> {
     try {
       const response = await fetch(`/api/project/${id}`, {
@@ -362,7 +423,6 @@ export const api: API = {
     }
   },
 
-  // Gets all users
   async getAllUsers(token: string): Promise<APIResponse<string[]>> {
     try {
       const response = await fetch("/api/users/all", {