feat: add eslint-plugin-tsdoc (#430)

* feat: add eslint-plugin-tsdoc

* feat(doc): update current jsdoc to tsdoc specification

* chore: update deps

* feat: update warn to error for jsdoc and tsdoc

* chore(doc): lint

src/views/components/calendar/CalendarBottomBar.tsx

@@ -20,8 +20,8 @@ type CalendarBottomBarProps = {
 /**
  * Renders the bottom bar of the calendar component.
  *
- * @param {Object[]} courses - The list of courses to display in the calendar.
- * @returns {JSX.Element} The rendered bottom bar component.
+ * @param courses - The list of courses to display in the calendar.
+ * @returns The rendered bottom bar component.
  */
 export default function CalendarBottomBar({ courseCells, setCourse }: CalendarBottomBarProps): JSX.Element {
     const asyncCourseCells = courseCells?.filter(block => block.async);

src/views/components/calendar/CalendarCourseCell.tsx

@@ -26,14 +26,12 @@ export interface CalendarCourseCellProps {
 /**
  * Renders a cell for a calendar course.
  *
- * @component
- * @param {CalendarCourseCellProps} props - The component props.
- * @param {string} props.courseDeptAndInstr - The course department and instructor.
- * @param {string} props.timeAndLocation - The time and location of the course.
- * @param {StatusType} props.status - The status of the course.
- * @param {Colors} props.colors - The colors for styling the cell.
- * @param {string} props.className - Additional CSS class name for the cell.
- * @returns {JSX.Element} The rendered component.
+ * @param courseDeptAndInstr - The course department and instructor.
+ * @param timeAndLocation - The time and location of the course.
+ * @param status - The status of the course.
+ * @param colors - The colors for styling the cell.
+ * @param className - Additional CSS class name for the cell.
+ * @returns The rendered component.
  */
 export default function CalendarCourseCell({
     courseDeptAndInstr,

src/views/components/calendar/CalendarCourseCellColorPicker/ColorPatch.tsx

@@ -15,12 +15,10 @@ interface ColorPatchProps {
 /**
  * Renders a color patch square used in the CalendarCourseCellColorPicker component.
  *
- * @param {Object} props - The component props.
- * @param {string} props.color - The color value (as a hex string with a hash prefix) to display in the patch.
- * @param {boolean} props.isSelected - Indicates whether the patch is selected.
- * @param {Function} props.handleSetSelectedColor - Function from parent component to control selection state of a patch.
- *                                                  color is a hex string with a hash prefix.
- * @returns {JSX.Element} The rendered color patch button.
+ * @param color - The color value (as a hex string with a hash prefix) to display in the patch.
+ * @param isSelected - Indicates whether the patch is selected.
+ * @param handleSetSelectedColor - Function from parent component to control selection state of a patch.
+ * @returns The rendered color patch button.
  */
 export default function ColorPatch({ color, isSelected, handleSetSelectedColor }: ColorPatchProps): JSX.Element {
     const handleClick = () => {

src/views/components/calendar/CalendarCourseCellColorPicker/CourseCellColorPicker.tsx

@@ -61,10 +61,14 @@ export interface CourseCellColorPickerProps {
 }
 
 /**
- * @param {CourseCellColorPickerProps} props - the props for the component
- * @param {React.Dispatch<React.SetStateAction<string | null>>} props.setSelectedColor - set state function passed down from the parent component
- * @param {boolean} props.isInvertColorsToggled - boolean state passed down from the parent component that indicates whether the color picker is in invert colors mode
- * @param {React.Dispatch<React.SetStateAction<boolean>>} props.setIsInvertColorsToggled - set state function passed down from the parent component to set invert colors mode
+ * The CourseCellColorPicker component that displays a color palette with a list of color patches.
+ *
+ * @remarks This component is available when a user hovers over a course cell in their calendar to
+ * color for the course cell. The user can set any valid hex color they want.
+ *
+ * @param setSelectedColor - Set state function passed down from the parent component
+ * @param isInvertColorsToggled - Boolean state passed down from the parent component that indicates whether the color picker is in invert colors mode
+ * @param setIsInvertColorsToggled - Set state function passed down from the parent component to set invert colors mode
  * that will be called when a color is selected. The user can set any valid hex color they want.
  *
  * @example
@@ -80,9 +84,7 @@ export interface CourseCellColorPickerProps {
  *   );
  * ```
  *
- * @returns {JSX.Element} - the color picker component that displays a color palette with a list of color patches.
- * This component is available when a user hovers over a course cell in their calendar to
- * color for the course cell. The user can set any valid hex color they want.
+ * @returns The color picker component that displays a color palette with a list of color patches.
  */
 export default function CourseCellColorPicker({
     setSelectedColor: setFinalColor,

src/views/components/calendar/CalendarCourseCellColorPicker/HexColorEditor.tsx

@@ -14,11 +14,10 @@ export interface HexColorEditorProps {
 /**
  * Utility component to allow the user to enter a valid hex color code
  *
- * @param {HexColorEditorProps} props - the props for the component
- * @param {string} props.hexCode - the current hex color code displayed in this component. Note that this code does not
+ * @param hexCode - The current hex color code displayed in this component. Note that this code does not
  * include the leading '#' character since it is already included in the component. Passed down from the parent component.
- * @param {React.Dispatch<React.SetStateAction<string>>} props.setHexCode - set state fn to control the hex color code from parent
- * @returns {JSX.Element} - the hex color editor component
+ * @param setHexCode - Set state fn to control the hex color code from parent
+ * @returns The HexColorEditor component
  */
 export default function HexColorEditor({ hexCode, setHexCode }: HexColorEditorProps): JSX.Element {
     const baseColor = React.useMemo(() => getThemeColorHexByName('ut-gray'), []);

src/views/components/calendar/CalendarGrid.tsx

@@ -43,7 +43,11 @@ function makeGridRow(row: number, cols: number): JSX.Element {
 
 /**
  * Grid of CalendarGridCell components forming the user's course schedule calendar view
- * @param props
+ *
+ * @param courseCells - The courses to display on the calendar
+ * @param saturdayClass - Whether the user has a Saturday class
+ * @param setCourse - Function to set the course to display in the course details panel
+ * @returns The CalendarGrid component
  */
 export default function CalendarGrid({
     courseCells,

src/views/components/calendar/CalendarGridCell.tsx

@@ -7,15 +7,18 @@ interface Props {
 
 /**
  * Component representing each 1 hour time block of a calendar
- * @param props
+ *
+ * @param row - The row of the cell
+ * @param col - The column of the cell
+ * @returns The CalendarCell component
  */
-function CalendarCell(props: Props): JSX.Element {
+function CalendarCell({ row, col }: Props): JSX.Element {
     return (
         <div
             className='h-full w-full flex items-center border-b border-r border-gray-300'
             style={{
-                gridColumn: props.col + 3,
-                gridRow: `${2 * props.row + 2} / ${2 * props.row + 4}`,
+                gridColumn: col + 3,
+                gridRow: `${2 * row + 2} / ${2 * row + 4}`,
             }}
         >
             <div className='h-0 w-full border-t border-gray-300/25' />

src/views/components/common/ConflictsWithWarning.tsx

@@ -15,7 +15,9 @@ export interface ConflictsWithWarningProps {
  * The ConflictsWithWarning component is used to display a warning message when a course conflicts
  * with another course as part of the labels and details section
  *
- * @param props ConflictsWithWarningProps
+ * @param className - The class name for the component
+ * @param conflicts - The courses that conflict with the current course
+ * @returns The ConflictsWithWarning component
  */
 export default function ConflictsWithWarning({ className, conflicts }: ConflictsWithWarningProps): JSX.Element {
     return (

src/views/components/common/CourseStatus.tsx

@@ -17,7 +17,9 @@ export interface CourseStatusProps {
 /**
  * The CourseStatus component as per the Labels and Details Figma section
  *
- * @param props CourseStatusProps
+ * @param status - The status of the course
+ * @param size - The size of the component
+ * @returns The CourseStatus component
  */
 export default function CourseStatus({ status, size }: CourseStatusProps): JSX.Element {
     const statusIconSizeClass = clsx({

src/views/components/common/List.tsx

@@ -70,7 +70,9 @@ function Item<T>(props: {
  * `List` is a functional component that displays a course meeting.
  *
  * @example
+ * ```
  * <List draggableElements={elements} />
+ * ```
  */
 function List<T>({ draggables, itemKey, children, onReordered, gap }: ListProps<T>): JSX.Element {
     const [items, setItems] = useState(wrap(draggables, itemKey));

src/views/components/common/LogoIcon.tsx

@@ -2,10 +2,15 @@ import clsx from 'clsx';
 import type { SVGProps } from 'react';
 import React from 'react';
 
+interface LogoIconProps {
+    className?: string;
+}
+
 /**
  * Renders the logo icon.
- * @param {SVGProps<SVGSVGElement>} props - The SVG props.
- * @returns {JSX.Element} The rendered logo icon.
+ *
+ * @param props - The SVG props.
+ * @returns The rendered logo icon.
  */
 export function LogoIcon(props: SVGProps<SVGSVGElement>): JSX.Element {
     return (
@@ -20,11 +25,11 @@ export function LogoIcon(props: SVGProps<SVGSVGElement>): JSX.Element {
 
 /**
  * Renders the small logo.
- * @param {Object} props - The component props.
- * @param {string} props.className - The class name for the logo container.
- * @returns {JSX.Element} The rendered small logo.
+ *
+ * @param className - The class name for the logo container.
+ * @returns The rendered small logo.
  */
-export function SmallLogo({ className }: { className?: string }): JSX.Element {
+export function SmallLogo({ className }: LogoIconProps): JSX.Element {
     return (
         <div className={clsx('flex items-center gap-2', className)}>
             <LogoIcon />
@@ -43,11 +48,11 @@ export function SmallLogo({ className }: { className?: string }): JSX.Element {
 
 /**
  * Renders the large logo.
- * @param {Object} props - The component props.
- * @param {string} props.className - The class name for the logo container.
- * @returns {JSX.Element} The rendered large logo.
+ *
+ * @param className - The class name for the logo container.
+ * @returns The rendered large logo.
  */
-export function LargeLogo({ className }: { className?: string }): JSX.Element {
+export function LargeLogo({ className }: LogoIconProps): JSX.Element {
     return (
         <div className={clsx('flex items-center gap-2', className)}>
             <LogoIcon className='h-12 w-12' />

src/views/components/common/PopupCourseBlock.tsx

@@ -25,7 +25,11 @@ export interface PopupCourseBlockProps {
 /**
  * The "course block" to be used in the extension popup.
  *
- * @param props PopupCourseBlockProps
+ * @param className - The class name to apply to the component.
+ * @param course - The course object to display.
+ * @param colors - The colors to use for the course block.
+ * @param dragHandleProps - The drag handle props for the course block.
+ * @returns The rendered PopupCourseBlock component.
  */
 export default function PopupCourseBlock({
     className,

src/views/components/common/Prompt.tsx

@@ -18,13 +18,15 @@ export interface PromptDialogProps {
 
 /**
  * A reusable dialog component that can be used to display a prompt to the user.
- * @param {PromptDialogProps} props.isOpen - Whether the dialog is open or not.
- * @param {Function} props.onClose - A function to call when the user exits the dialog.
- * @param {React.ReactElement<typeof Text>} props.title - The title of the dialog.
- * @param {React.ReactElement<typeof Text>} props.content - The content of the dialog.
- * @param {React.ReactElement<typeof Button>[]} props.children - The buttons to display in the dialog.
+ *
+ * @param isOpen - Whether the dialog is open or not.
+ * @param onClose - A function to call when the user exits the dialog.
+ * @param title - The title of the dialog.
+ * @param content - The content of the dialog.
+ * @param children - The buttons to display in the dialog.
+ * @returns The rendered PromptDialog component.
  */
-function PromptDialog({ isOpen, onClose, title, content, children }: PromptDialogProps) {
+function PromptDialog({ isOpen, onClose, title, content, children }: PromptDialogProps): JSX.Element {
     return (
         <Transition appear show={isOpen} as={React.Fragment}>
             <Dialog as='div' onClose={onClose} className='relative z-50'>

src/views/components/common/ScheduleTotalHoursAndCourses.tsx

@@ -13,7 +13,10 @@ export interface ScheduleTotalHoursAndCoursesProps {
 /**
  * The ScheduleTotalHoursAndCourses as per the Labels and Details Figma section
  *
- * @param props ScheduleTotalHoursAndCoursesProps
+ * @param scheduleName - The name of the schedule.
+ * @param totalHours - The total number of hours.
+ * @param totalCourses - The total number of courses.
+ * @returns The rendered ScheduleTotalHoursAndCourses component.
  */
 export default function ScheduleTotalHoursAndCourses({
     scheduleName,

src/views/components/common/SwitchButton.tsx

@@ -9,11 +9,9 @@ type ToggleSwitchProps = {
 /**
  * A custom switch button component.
  *
- * @component
- * @param {Object} props - The component props.
- * @param {boolean} [props.isChecked=true] - The initial checked state of the switch button.
- * @param {Function} props.onChange - The callback function to be called when the switch button is toggled.
- * @returns {JSX.Element} The rendered SwitchButton component.
+ * @param isChecked - The initial checked state of the switch button.
+ * @param onChange - The callback function to be called when the switch button is toggled.
+ * @returns The rendered SwitchButton component.
  */
 const SwitchButton = ({ isChecked = true, onChange }: ToggleSwitchProps): JSX.Element => {
     const [enabled, setEnabled] = useState(isChecked);

src/views/components/common/UpdateText.tsx

@@ -12,8 +12,7 @@ export type UpdateTextProps = {
  * UpdateText component displays a message indicating that the extension has been updated
  * and lists the unique course numbers from the old version.
  *
- * @param props - The properties object.
- * @param props.courses - An array of course unique numbers to be displayed.
+ * @param courses - An array of course unique numbers to be displayed.
  * @returns The rendered UpdateText component.
  */
 export default function UpdateText({ courses }: UpdateTextProps): JSX.Element {

src/views/components/injected/CourseCatalogInjectedPopup/CourseCatalogInjectedPopup.tsx

@@ -11,19 +11,17 @@ import HeadingAndActions from './HeadingAndActions';
 /**
  * Props for the CourseCatalogInjectedPopup component.
  */
-export type CourseCatalogInjectedPopupProps = DialogProps & {
+export interface CourseCatalogInjectedPopupProps extends DialogProps {
     course: Course;
-};
+}
 
 /**
  * CourseCatalogInjectedPopup component displays a popup with course details.
  *
- * @component
- * @param {CourseCatalogInjectedPopupProps} props - The component props.
- * @param {Course} props.course - The course object containing course details.
- * @param {Schedule} props.activeSchedule - The active schedule object.
- * @param {Function} props.onClose - The function to close the popup.
- * @returns {JSX.Element} The CourseCatalogInjectedPopup component.
+ * @param course - The course object containing course details.
+ * @param activeSchedule - The active schedule object.
+ * @param onClose - The function to close the popup.
+ * @returns The CourseCatalogInjectedPopup component.
  */
 function CourseCatalogInjectedPopup({ course, ...rest }: CourseCatalogInjectedPopupProps): JSX.Element {
     const emptyRef = React.useRef<HTMLDivElement>(null);

src/views/components/injected/CourseCatalogInjectedPopup/Description.tsx

@@ -32,10 +32,8 @@ const fetchDescription = async (course: Course): Promise<string[]> => {
 /**
  * Renders the description component.
  *
- * @component
- * @param {DescriptionProps} props - The component props.
- * @param {Course} props.course - The course for which to display the description.
- * @returns {JSX.Element} The rendered description component.
+ * @param course - The course for which to display the description.
+ * @returns The rendered description component.
  */
 export default function Description({ course }: DescriptionProps): JSX.Element {
     const [description, setDescription] = React.useState<string[]>([]);

src/views/components/injected/CourseCatalogInjectedPopup/GradeDistribution.tsx

@@ -48,10 +48,8 @@ const GRADE_COLORS = {
 /**
  * Renders the grade distribution chart for a specific course.
  *
- * @component
- * @param {GradeDistributionProps} props - The component props.
- * @param {Course} props.course - The course for which to display the grade distribution.
- * @returns {JSX.Element} The grade distribution chart component.
+ * @param course - The course for which to display the grade distribution.
+ * @returns The grade distribution chart component.
  */
 export default function GradeDistribution({ course }: GradeDistributionProps): JSX.Element {
     const [semester, setSemester] = useState('Aggregate');

src/views/components/injected/CourseCatalogInjectedPopup/HeadingAndActions.tsx

@@ -22,6 +22,14 @@ import Reviews from '~icons/material-symbols/reviews';
 
 const { openNewTab, addCourse, removeCourse, openCESPage } = background;
 
+/**
+ * Capitalizes the first letter of a string and converts the rest of the letters to lowercase.
+ *
+ * @param str - The string to be capitalized.
+ * @returns The capitalized string.
+ */
+const capitalizeString = (str: string) => str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
+
 interface HeadingAndActionProps {
     /* The course to display */
     course: Course;
@@ -31,22 +39,13 @@ interface HeadingAndActionProps {
     onClose: () => void;
 }
 
-/**
- * Capitalizes the first letter of a string and converts the rest of the letters to lowercase.
- *
- * @param str - The string to be capitalized.
- * @returns The capitalized string.
- */
-const capitalizeString = (str: string) => str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
-
 /**
  * Renders the heading component for the CoursePopup component.
  *
- * @param {HeadingAndActionProps} props - The component props.
- * @param {Course} props.course - The course object containing course details.
- * @param {Schedule} props.activeSchedule - The active schedule object.
- * @param {Function} props.onClose - The function to close the popup.
- * @returns {JSX.Element} The rendered component.
+ * @param course - The course object containing course details.
+ * @param activeSchedule - The active schedule object.
+ * @param onClose - The function to close the popup.
+ * @returns The rendered component.
  */
 export default function HeadingAndActions({ course, activeSchedule, onClose }: HeadingAndActionProps): JSX.Element {
     const { courseName, department, number: courseNumber, uniqueId, instructors, flags, schedule, core } = course;

src/views/components/injected/RecruitmentBanner/RecruitmentBanner.tsx

@@ -12,6 +12,7 @@ const RECRUIT_FROM_DEPARTMENTS = ['C S', 'ECE', 'MIS', 'CSE', 'EE', 'ITD', 'DES'
 
 /**
  * This adds a new column to the course catalog table header.
+ *
  * @returns a react portal to the new column or null if the column has not been created yet.
  */
 export default function RecruitmentBanner(): JSX.Element | null {
@@ -53,7 +54,8 @@ export default function RecruitmentBanner(): JSX.Element | null {
 
 /**
  * Determines if recruitment can be done from the current department.
- * @returns {boolean} True if recruitment can be done from the current department, false otherwise.
+ *
+ * @returns True if recruitment can be done from the current department, false otherwise.
  */
 export const canRecruitFrom = (): boolean => {
     const params = ['fos_fl', 'fos_cn'];

src/views/components/settings/Settings.tsx

@@ -1,4 +1,4 @@
-import addCourse from '@pages/background/lib/addCourse';
+// import addCourse from '@pages/background/lib/addCourse';
 import { addCourseByURL } from '@pages/background/lib/addCourseByURL';
 import { deleteAllSchedules } from '@pages/background/lib/deleteSchedule';
 import { initSettings, OptionsStore } from '@shared/storage/OptionsStore';
@@ -14,10 +14,10 @@ import SwitchButton from '@views/components/common/SwitchButton';
 import Text from '@views/components/common/Text/Text';
 import useChangelog from '@views/hooks/useChangelog';
 import useSchedules from '@views/hooks/useSchedules';
-import { CourseCatalogScraper } from '@views/lib/CourseCatalogScraper';
-import getCourseTableRows from '@views/lib/getCourseTableRows';
+// import { CourseCatalogScraper } from '@views/lib/CourseCatalogScraper';
+// import getCourseTableRows from '@views/lib/getCourseTableRows';
 import { GitHubStatsService, LONGHORN_DEVELOPERS_ADMINS, LONGHORN_DEVELOPERS_SWE } from '@views/lib/getGitHubStats';
-import { SiteSupport } from '@views/lib/getSiteSupport';
+// import { SiteSupport } from '@views/lib/getSiteSupport';
 import { getUpdatedAtDateTimeString } from '@views/lib/getUpdatedAtDateTimeString';
 import clsx from 'clsx';
 import React, { useCallback, useEffect, useState } from 'react';