diff --git a/frontend/src/API/API.ts b/frontend/src/API/API.ts index cfb53b0..47299f3 100644 --- a/frontend/src/API/API.ts +++ b/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 { + /** 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>} A promise containing the API response with the user data. + */ registerUser(user: NewUser): Promise>; - /** 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>} A promise containing the API response with the removed user data. + */ removeUser(username: string, token: string): Promise>; - /** 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>} A promise containing the API response indicating if the user is a project manager. + */ checkIfProjectManager( username: string, projectName: string, token: string, ): Promise>; - /** Login */ + + /** Logs in a user with the provided credentials. + * @param {NewUser} NewUser The user object containing username and password. + * @returns {Promise>} A promise resolving to an API response with a token. + */ login(NewUser: NewUser): Promise>; - /** Renew the token */ + + /** + * Renew the token + * @param {string} token The current authentication token. + * @returns {Promise>} A promise resolving to an API response with a renewed token. + */ renewToken(token: string): Promise>; + /** 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>} A promise resolving to an API response with the created project. + */ createProject( project: NewProject, token: string, ): Promise>; - /** Submit a weekly report */ + + /** Submits a weekly report + * @param {NewWeeklyReport} weeklyReport The weekly report object. + * @param {string} token The authentication token. + * @returns {Promise>} A promise resolving to an API response with the submitted report. + */ submitWeeklyReport( - project: NewWeeklyReport, + weeklyReport: NewWeeklyReport, token: string, ): Promise>; - /**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>} A promise resolving to an API response with the retrieved report. + */ getWeeklyReport( username: string, projectName: string, week: string, token: string, ): Promise>; + /** * 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} A list of weekly reports @@ -61,15 +111,27 @@ interface API { projectName: string, token: string, ): Promise>; - /** Gets all the projects of a user*/ + + /** Gets all the projects of a user + * @param {string} token - The authentication token. + * @returns {Promise>} A promise containing the API response with the user's projects. + */ getUserProjects(token: string): Promise>; - /** Gets a project from id*/ + + /** Gets a project by its id. + * @param {number} id The id of the project to retrieve. + * @returns {Promise>} A promise resolving to an API response containing the project data. + */ getProject(id: number): Promise>; - /** Gets a project from id*/ + + /** Gets a list of all users. + * @param {string} token The authentication token of the requesting user. + * @returns {Promise>} A promise resolving to an API response containing the list of users. + */ getAllUsers(token: string): Promise>; } -// Export an instance of the API +/** An instance of the API */ export const api: API = { async registerUser(user: NewUser): Promise> { 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> { try { const response = await fetch(`/api/project/${id}`, { @@ -362,7 +423,6 @@ export const api: API = { } }, - // Gets all users async getAllUsers(token: string): Promise> { try { const response = await fetch("/api/users/all", { diff --git a/frontend/src/Components/AddProject.tsx b/frontend/src/Components/AddProject.tsx index 45814e3..f5f4a08 100644 --- a/frontend/src/Components/AddProject.tsx +++ b/frontend/src/Components/AddProject.tsx @@ -7,7 +7,7 @@ import Button from "./Button"; /** * Tries to add a project to the system - * @param props - Project name and description + * @param {Object} props - Project name and description * @returns {boolean} True if created, false if not */ function CreateProject(props: { name: string; description: string }): boolean { @@ -34,8 +34,8 @@ function CreateProject(props: { name: string; description: string }): boolean { } /** - * Tries to add a project to the system - * @returns {JSX.Element} UI for project adding + * Provides UI for adding a project to the system. + * @returns {JSX.Element} - Returns the component UI for adding a project */ function AddProject(): JSX.Element { const [name, setName] = useState(""); diff --git a/frontend/src/Components/AllTimeReportsInProject.tsx b/frontend/src/Components/AllTimeReportsInProject.tsx index d05f92c..fcd0f8f 100644 --- a/frontend/src/Components/AllTimeReportsInProject.tsx +++ b/frontend/src/Components/AllTimeReportsInProject.tsx @@ -7,7 +7,7 @@ import { api } from "../API/API"; /** * Renders a component that displays all the time reports for a specific project. - * @returns JSX.Element representing the component. + * @returns {JSX.Element} representing the component. */ function AllTimeReportsInProject(): JSX.Element { const { projectName } = useParams();