From de74e9548465087d5ae1df613f0e0a15beccb2b7 Mon Sep 17 00:00:00 2001
From: Giang Vu <dhgiang.vu@gmail.com>
Date: Sun, 22 Sep 2024 23:29:18 +1000
Subject: [PATCH] docs: update comments / JSDoc

---
 frontend/src/components/BackButton.tsx       |  5 +++
 frontend/src/components/DisplayFile.tsx      |  7 ++++
 frontend/src/components/Footer.tsx           |  6 ++++
 frontend/src/components/Header.tsx           |  4 +++
 frontend/src/components/NextButton.tsx       |  4 +++
 frontend/src/components/ProceedButton.tsx    |  9 ++++++
 frontend/src/components/Sidebar.tsx          |  9 ++++++
 frontend/src/components/Spreadsheet.tsx      | 10 ++++++
 frontend/src/components/UploadButton.tsx     |  7 ++++
 frontend/src/components/UploadPopUp.tsx      |  7 ++++
 frontend/src/pages/Download.tsx              |  7 ++++
 frontend/src/pages/Enrolment.tsx             |  8 +++++
 frontend/src/pages/SemesterInfo.tsx          |  6 ++++
 frontend/src/pages/SendData.tsx              |  8 +++++
 frontend/src/pages/TimetableMod.tsx          |  7 ++++
 frontend/src/pages/spreadsheets/Building.tsx |  4 +++
 frontend/src/pages/spreadsheets/Room.tsx     |  4 +++
 frontend/src/pages/spreadsheets/Unit.tsx     |  4 +++
 frontend/src/routes.tsx                      |  7 +++-
 frontend/src/scripts/api.ts                  | 12 ++++++-
 frontend/src/scripts/handleInput.ts          | 32 ++++++++++++++----
 frontend/src/scripts/persistence.ts          | 34 ++++++++++++++++++--
 frontend/src/styles/enrolment.css            |  8 ++---
 23 files changed, 194 insertions(+), 15 deletions(-)

diff --git a/frontend/src/components/BackButton.tsx b/frontend/src/components/BackButton.tsx
index de85c97..b30dedf 100644
--- a/frontend/src/components/BackButton.tsx
+++ b/frontend/src/components/BackButton.tsx
@@ -1,6 +1,11 @@
 import ArrowBackIcon from '@mui/icons-material/ArrowBack';
 import { Button } from '@mui/material';
 
+/**
+ * React component for a back button with outlined style.
+ * Displays a button with an arrow icon and text 'Back'.
+ * @returns JSX element representing the back button
+ */
 export default function BackButton() {
   return (
     <Button 
diff --git a/frontend/src/components/DisplayFile.tsx b/frontend/src/components/DisplayFile.tsx
index 8b45ef5..7dadda0 100644
--- a/frontend/src/components/DisplayFile.tsx
+++ b/frontend/src/components/DisplayFile.tsx
@@ -5,6 +5,13 @@ interface DisplayFileProps {
   fileChosen: File | null;
 }
 
+/**
+ * Renders the file chosen for display.
+ * 
+ * @param {DisplayFileProps} fileChosen - The file object to be displayed.
+ * @returns The component displaying the chosen file or an empty 
+ * Box if no file is chosen.
+ */
 export default function DisplayFile({fileChosen}: DisplayFileProps) {
     if (fileChosen === null) {
       return <Box/>;
diff --git a/frontend/src/components/Footer.tsx b/frontend/src/components/Footer.tsx
index b9dc5e3..4ebbcd1 100644
--- a/frontend/src/components/Footer.tsx
+++ b/frontend/src/components/Footer.tsx
@@ -1,5 +1,11 @@
 import { Box } from "@mui/material";
 
+/**
+ * React component for rendering a fixed position footer.
+ * 
+ * @param children - The content to be displayed inside the footer.
+ * @returns JSX element representing the styled footer component.
+ */
 export default function Footer({ children } : { children?: React.ReactNode }) {
   const footerStyle = {
     backgroundColor: "#f05a22",
diff --git a/frontend/src/components/Header.tsx b/frontend/src/components/Header.tsx
index 6ec501f..aefda83 100644
--- a/frontend/src/components/Header.tsx
+++ b/frontend/src/components/Header.tsx
@@ -1,6 +1,10 @@
 import { Box } from "@mui/material";
 import VIT_Logo from '../assets/logo.png';
 
+/**
+ * React component for rendering the header section.
+ * @returns JSX element representing the header with a logo.
+ */
 export default function Header() {
     const headerStyle = {
         backgroundColor: "#F5F5f5",
diff --git a/frontend/src/components/NextButton.tsx b/frontend/src/components/NextButton.tsx
index 4fa3fb0..2ab09c0 100644
--- a/frontend/src/components/NextButton.tsx
+++ b/frontend/src/components/NextButton.tsx
@@ -1,6 +1,10 @@
 import ArrowForwardIcon from '@mui/icons-material/ArrowForward';
 import { Button } from '@mui/material';
 
+/**
+ * Component for rendering a button with an arrow icon indicating next action.
+ * @returns JSX element representing the NextButton component
+ */
 export default function NextButton() {
   return (
     <Button 
diff --git a/frontend/src/components/ProceedButton.tsx b/frontend/src/components/ProceedButton.tsx
index 8630d0c..b73b8ca 100644
--- a/frontend/src/components/ProceedButton.tsx
+++ b/frontend/src/components/ProceedButton.tsx
@@ -5,6 +5,15 @@ interface ProceedButtonProps {
   fileChosen: File | null;
 }
 
+/**
+ * Functional component for rendering a Proceed Button based on whether a file 
+ * is chosen or not.
+ * 
+ * @param {ProceedButtonProps} fileChosen - Props object containing the fileChosen 
+ * boolean value
+ * @returns A Button component that allows the user to proceed 
+ * to a specific route when clicked
+ */
 export default function ProceedButton({ fileChosen }: ProceedButtonProps) {
   const navigate = useNavigate();
   if (fileChosen === null) {
diff --git a/frontend/src/components/Sidebar.tsx b/frontend/src/components/Sidebar.tsx
index 759ace2..fd86d43 100644
--- a/frontend/src/components/Sidebar.tsx
+++ b/frontend/src/components/Sidebar.tsx
@@ -16,6 +16,15 @@ interface SidebarProps {
 }
 const drawerWidth = 240;
 
+/**
+ * Renders a sidebar component with navigation links to Campus, Building, Room, 
+ * Course, and Unit.
+ * 
+ * @param {SidebarProps} props - The properties passed to Sidebar component
+ * @param {number} props.marginTop - The top margin of the sidebar.
+ * @param {number} props.width - The width of the sidebar.
+ * @returns Sidebar component with navigation links.
+ */
 export default function Sidebar({ marginTop, width }: SidebarProps) {
   return (
     <Drawer
diff --git a/frontend/src/components/Spreadsheet.tsx b/frontend/src/components/Spreadsheet.tsx
index d5805d6..6d71e74 100644
--- a/frontend/src/components/Spreadsheet.tsx
+++ b/frontend/src/components/Spreadsheet.tsx
@@ -11,6 +11,16 @@ interface SpreadsheetProps {
   columns?: jspreadsheet.Column[]
 }
 
+/**
+ * Component for rendering a spreadsheet with customisable headers and storage 
+ * functionality.
+ * 
+ * @param {SpreadsheetProps} props - The properties passed to Spreadsheet component 
+ * @param {SpreadsheetProps.headers} props.headers - Array of header names for the spreadsheet columns.
+ * @param {SpreadsheetProps.storageKey} props.storageKey - Key for storing and retrieving spreadsheet data 
+ * in storage (i.e. indexedDB).
+ * @return Div containing a spreadsheet and button to add row.
+ */
 export default function Spreadsheet({ headers, storageKey, ...other }: SpreadsheetProps) {
   const jRef = useRef<null | JspreadsheetInstanceElement>(null);
 
diff --git a/frontend/src/components/UploadButton.tsx b/frontend/src/components/UploadButton.tsx
index c89643f..892105d 100644
--- a/frontend/src/components/UploadButton.tsx
+++ b/frontend/src/components/UploadButton.tsx
@@ -20,6 +20,13 @@ const VisuallyHiddenInput = styled("input")({
   width: 1,
 });
 
+/**
+ * Functional component for an upload button that allows users to select and 
+ * upload a file.
+ * 
+ * @param {InputFileUploadProps.setFileChosen} setFileChosen - Callback function to set the chosen file.
+ * @returns Upload button component with file selection and upload functionality.
+ */
 export default function UploadButton ({ setFileChosen }: InputFileUploadProps) {
 
   // Handler for file selection
diff --git a/frontend/src/components/UploadPopUp.tsx b/frontend/src/components/UploadPopUp.tsx
index 5661702..5cbab98 100644
--- a/frontend/src/components/UploadPopUp.tsx
+++ b/frontend/src/components/UploadPopUp.tsx
@@ -7,6 +7,13 @@ import { Button } from "@mui/material";
 import ProceedButton from "./ProceedButton.tsx";
 import DisplayFile from "./DisplayFile.tsx";
 
+/**
+ * UploadPopUp component for displaying a modal with file upload functionality.
+ * Manages the state of the modal being open or closed and the file chosen
+ * for upload.
+ * 
+ * @returns A button to open a modal with file display, upload button, and proceed button.
+ */
 export default function UploadPopUp() {
   const [open, setOpen] = useState(false);
   const [fileChosen, setFileChosen] = useState<File | null>(null);
diff --git a/frontend/src/pages/Download.tsx b/frontend/src/pages/Download.tsx
index c9e7208..2782303 100644
--- a/frontend/src/pages/Download.tsx
+++ b/frontend/src/pages/Download.tsx
@@ -1,5 +1,12 @@
 import { Link } from "react-router-dom";
 
+/**
+ * Renders the Download page component.
+ * Displays a heading for downloading generated timetables and a link to go 
+ * back to the timetable modification page.
+ * @returns JSX element representing the Download page
+ * TODO: TO BE IMPLEMENTED
+ */
 export default function Download() {
   return (
     <>
diff --git a/frontend/src/pages/Enrolment.tsx b/frontend/src/pages/Enrolment.tsx
index 731688c..653367e 100644
--- a/frontend/src/pages/Enrolment.tsx
+++ b/frontend/src/pages/Enrolment.tsx
@@ -4,6 +4,14 @@ import UploadPopUp from "../components/UploadPopUp.tsx";
 import Header from "../components/Header.tsx";
 import Footer from "../components/Footer.tsx";
 import Photo from "../assets/frontpage.jpg";
+
+/**
+ * Renders the Starter Page component with specific time and tabler styles.
+ * Includes a description box with time and tabler elements, lorem ipsum text, 
+ * and an UploadPopUp component.
+ * Utilizes the Header and Footer components for layout consistency.
+ * TODO: replace lorem ipsum with actual texts, replace better quality img
+ */
 export default function StarterPage() {
   const timeStyle = {
     color: "#f05a22",
diff --git a/frontend/src/pages/SemesterInfo.tsx b/frontend/src/pages/SemesterInfo.tsx
index 6c4576b..4a00ccc 100644
--- a/frontend/src/pages/SemesterInfo.tsx
+++ b/frontend/src/pages/SemesterInfo.tsx
@@ -6,6 +6,12 @@ import '../styles/seminfo.css';
 import NextButton from "../components/NextButton.tsx";
 import BackButton from "../components/BackButton.tsx";
 
+/**
+ * Renders the SemesterInfo component with a header, sidebar, spreadsheet, 
+ * and navigation buttons.
+ * 
+ * @returns JSX element representing the SemesterInfo component
+ */
 export default function SemesterInfo() {
   return (
     <div>
diff --git a/frontend/src/pages/SendData.tsx b/frontend/src/pages/SendData.tsx
index d35e43e..597084e 100644
--- a/frontend/src/pages/SendData.tsx
+++ b/frontend/src/pages/SendData.tsx
@@ -8,6 +8,14 @@ import { getTimetableProblem } from "../scripts/handleInput";
 import { useState } from "react";
 import { fetchTimetableSolution } from "../scripts/api";
 
+/**
+ * Page for containing UI elements that allow user to send input data to backend.
+ * Temporarily has a display for backend's response to confirm successful sending 
+ *                      (will remove and replace with display page in next sprint).
+ * 
+ * @returns button for sending timetable problem and temporary display for timetable solution.
+ * TODO: change button and UI elements to fit with VIT themes.
+ */
 export default function SendData() {
 
   const [isGenerated, setIsGenerated] = useState("");
diff --git a/frontend/src/pages/TimetableMod.tsx b/frontend/src/pages/TimetableMod.tsx
index 9872287..ff9a38b 100644
--- a/frontend/src/pages/TimetableMod.tsx
+++ b/frontend/src/pages/TimetableMod.tsx
@@ -1,5 +1,12 @@
 import { Link } from "react-router-dom";
 
+/**
+ * Renders the TimetableMod component to display and modify the generated 
+ * timetable.
+ * Allows users to navigate back to the campus information page and proceed to 
+ * the download page.
+ * @returns JSX element containing the page content with navigation links
+ */
 export default function TimetableMod() {
   return (
     <>
diff --git a/frontend/src/pages/spreadsheets/Building.tsx b/frontend/src/pages/spreadsheets/Building.tsx
index d195d23..be3ccc9 100644
--- a/frontend/src/pages/spreadsheets/Building.tsx
+++ b/frontend/src/pages/spreadsheets/Building.tsx
@@ -1,6 +1,10 @@
 import Spreadsheet from '../../components/Spreadsheet.tsx'
 import { DB_BUILDINGS } from '../../scripts/persistence.ts';
 
+/**
+ * 
+ * @returns Spreadsheet input page for buildings information.
+ */
 export default function Building() {
 
   return (
diff --git a/frontend/src/pages/spreadsheets/Room.tsx b/frontend/src/pages/spreadsheets/Room.tsx
index 42b78bd..e07db9d 100644
--- a/frontend/src/pages/spreadsheets/Room.tsx
+++ b/frontend/src/pages/spreadsheets/Room.tsx
@@ -1,6 +1,10 @@
 import Spreadsheet from '../../components/Spreadsheet.tsx'
 import { DB_ROOMS } from '../../scripts/persistence.ts';
 
+/**
+ * 
+ * @returns Spreadsheet input page for rooms information.
+ */
 export default function Room() {
 
   return (
diff --git a/frontend/src/pages/spreadsheets/Unit.tsx b/frontend/src/pages/spreadsheets/Unit.tsx
index bfa733d..b747cc3 100644
--- a/frontend/src/pages/spreadsheets/Unit.tsx
+++ b/frontend/src/pages/spreadsheets/Unit.tsx
@@ -1,6 +1,10 @@
 import Spreadsheet from '../../components/Spreadsheet.tsx'
 import { DB_UNITS } from '../../scripts/persistence.ts';
 
+/**
+ * 
+ * @returns Spreadsheet input page for units information.
+ */
 export default function Unit() {
 
   return (
diff --git a/frontend/src/routes.tsx b/frontend/src/routes.tsx
index 14b1270..a0d04eb 100644
--- a/frontend/src/routes.tsx
+++ b/frontend/src/routes.tsx
@@ -7,7 +7,12 @@ import Download from './pages/Download.tsx'
 import Enrolment from './pages/Enrolment.tsx'
 import SendData from './pages/SendData.tsx'
 
-
+/**
+ * Defines the routes configuration for the application.
+ * Each route specifies a path and the corresponding component to render.
+ * 
+ * An array of route objects, each containing path and element information.
+ */
 const routes = [
   {
     path: "/",
diff --git a/frontend/src/scripts/api.ts b/frontend/src/scripts/api.ts
index 7ef4939..af60362 100644
--- a/frontend/src/scripts/api.ts
+++ b/frontend/src/scripts/api.ts
@@ -1,5 +1,8 @@
+/* Timetable solver backend endpoint URL */
 const API_URL = 'http://localhost:8080/timetabling';
 
+/* =========================================== Defining types =========================================== */
+
 export type TimetableProblem = TimetableBase & {
   units: Unit[],
 }
@@ -42,8 +45,15 @@ export type Weekday = "MONDAY" | "TUESDAY" | "WEDNESDAY" | "THURSDAY" | "FRIDAY"
 
 export type Time = string;
 
+/* ====================================================================================================== */
+
 
-// API function(s)
+/**
+ * Sends the timetabling problem to backend for solving. Return the solution received.
+ * 
+ * @param problem A TimetableProblem is a list of units with no allocated time and room.
+ * @returns A TimetableSolution with all units allocated a time and a room.
+ */
 export async function fetchTimetableSolution(problem: TimetableProblem): Promise<TimetableSolution | null> {
   try {
     const response = await fetch(API_URL, {
diff --git a/frontend/src/scripts/handleInput.ts b/frontend/src/scripts/handleInput.ts
index f3c746e..629f45a 100644
--- a/frontend/src/scripts/handleInput.ts
+++ b/frontend/src/scripts/handleInput.ts
@@ -3,9 +3,12 @@ import { CellValue } from 'jspreadsheet-ce';
 import { TimetableProblem, Unit, Room } from './api';
 import { DB_UNITS, storeSpreadsheetData } from './persistence';
 
-/*
- * Return true if file is an Excel file
-*/
+/**
+ * Function to validate uploaded enrolment data file.
+ * 
+ * @param file enrolment data Excel file
+ * @returns true if uploaded file is an Excel file
+ */
 function isExcelFile(file: File) {
   const fileExtension = file.name.split('.').pop();
   if (fileExtension === undefined || !['xlsx', 'xls'].includes(fileExtension)) {
@@ -15,9 +18,12 @@ function isExcelFile(file: File) {
   return true;
 }
 
-/*
- * Return true if enrolment data header file matches expected format
-*/
+/**
+ * Function to validate uploaded enrolment data file.
+ * 
+ * @param inputHeader header row of enrolment data Excel file
+ * @returns true if header row matches expected format for parsing.
+ */
 function validateEnrolmentHeader(inputHeader: Row) {
   const header = ['StudentID', 'Student Name', 'Personal Email', 'University Email',
     'Student Type', 'Offer Type', 'Course Name', 'Campus', 'Original COE Start Date',
@@ -32,6 +38,12 @@ function validateEnrolmentHeader(inputHeader: Row) {
   }
 }
 
+/**
+ * Extract list of units from enrolment data and prefill spreadsheet input page.
+ * 
+ * @param enrolmentExcel enrolment data Excel file
+ * @returns enrolment data Excel file
+ */
 export async function getUnitsList(enrolmentExcel: File) {
   if (!isExcelFile(enrolmentExcel)) {
     throw new Error(
@@ -58,6 +70,14 @@ export async function getUnitsList(enrolmentExcel: File) {
   return enrolmentExcel;
 }
 
+/**
+ * Parse user input to create the timetabling problem.
+ * 
+ * @param enrolmentExcel enrolment data Excel file
+ * @param roomSpreadsheet information of all rooms (spreadsheet input from user)
+ * @param unitSpreadsheet information of all units (spreadsheet input from user)
+ * @returns a TimetableProblem, which includes all available rooms, start times and unallocated units
+ */
 export async function getTimetableProblem(enrolmentExcel: File, roomSpreadsheet: Record<string, CellValue>[], unitSpreadsheet: Record<string, CellValue>[]) {
   if (!isExcelFile(enrolmentExcel)) {
     throw new Error(
diff --git a/frontend/src/scripts/persistence.ts b/frontend/src/scripts/persistence.ts
index 57f6ccd..ecb9516 100644
--- a/frontend/src/scripts/persistence.ts
+++ b/frontend/src/scripts/persistence.ts
@@ -1,23 +1,25 @@
 import Dexie, { EntityTable } from "dexie";
 import { CellValue } from "jspreadsheet-ce";
 
+/* Define storage keys */
 const DB_NAME = 'TimetableInput';
 const DB_BUILDINGS = 'buildings';
 const DB_ROOMS = 'rooms';
 const DB_UNITS = 'units';
 
-
+/* Define record type of `file` objectStore */
 interface FileRecord {
   id: number;
   file: File;
 }
 
+/* Define record type of each spreadsheets objectStore */
 interface SpreadsheetRecord {
   id?: number;
   record: Record<string, CellValue>;
 }
 
-
+/* Initialise Dexie (indexedDB wrapper) */
 const db = new Dexie(DB_NAME) as Dexie & {
   files: EntityTable<FileRecord, 'id'>;
   buildings: EntityTable<SpreadsheetRecord, 'id'>;
@@ -25,6 +27,7 @@ const db = new Dexie(DB_NAME) as Dexie & {
   units: EntityTable<SpreadsheetRecord, 'id'>;
 };
 
+/* Initialise indexedDB objectStores */
 db.version(1).stores({
   files: '++id, file',
   buildings: '++id, record',
@@ -32,6 +35,14 @@ db.version(1).stores({
   units: '++id, record'
 });
 
+/**
+ * Save 1 file to the first row of the file table.
+ * Delete all other files.
+ * Intend for storing enrolment data Excel file.
+ * 
+ * @param file any file
+ * @returns id of saved row
+ */
 export async function storeFile(file: File): Promise<number> {
   await db.files.clear();
   const id = await db.files.add({
@@ -41,6 +52,12 @@ export async function storeFile(file: File): Promise<number> {
   return id;
 }
 
+/**
+ * Get first file saved to the `file` objectStore.
+ * Intend for getting saved enrolment data Excel file.
+ * 
+ * @returns file saved 
+ */
 export async function getFile(): Promise<File> {
   const file = await db.files.orderBy('id').first();
 
@@ -52,6 +69,13 @@ export async function getFile(): Promise<File> {
   return file.file;
 }
 
+/**
+ * Store data of an input spreadsheet to the corresponding objectStore in indexedDB.
+ * 
+ * @param data data in one spreadsheet page
+ * @param storageObject the key of the objectStore (table) of the database we want to store data into
+ * @returns void
+ */
 export async function storeSpreadsheetData(data: Record<string, CellValue>[], storageObject: string) {
   if (!data) {
     return;
@@ -88,6 +112,12 @@ export async function storeSpreadsheetData(data: Record<string, CellValue>[], st
   }
 }
 
+/**
+ * Get data from a specified indexedDB objectStore.
+ * 
+ * @param storageObject the key of the objectStore (table) that we want to get data out of
+ * @returns spreadsheet data
+ */
 export async function getSpreadsheetData(storageObject: string): Promise<Record<string, CellValue>[] | null> {
   try {
     if (storageObject === "buildings") {
diff --git a/frontend/src/styles/enrolment.css b/frontend/src/styles/enrolment.css
index ca0602e..f2bcc26 100644
--- a/frontend/src/styles/enrolment.css
+++ b/frontend/src/styles/enrolment.css
@@ -1,13 +1,11 @@
-/* Make sure the entire viewport height is used */
 .app-container {
   display: flex;
   flex-direction: column;
-  min-height: 100vh; /* Full viewport height */
+  min-height: 100vh;
 }
 
-/* Content area that grows to fill space */
 .content {
-  flex: 1; /* This allows the content to grow and push the footer down */
+  flex: 1;
   padding: 0;
   display: grid;
   grid-template-columns: 1fr 1fr;
@@ -27,7 +25,7 @@
 }
 
 .imageBox {
-  overflow: hidden; /* Hide any overflow content */
+  overflow: hidden;
   position: relative;
 }
 body {