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/shared/messages/CESMessage.ts

@@ -2,7 +2,7 @@ interface CESMessage {
     /**
      * Opens the CES page for the specified instructor
      *
-     * @param data first and last name of the instructor
+     * @param data - First and last name of the instructor
      */
     openCESPage: (data: { instructorFirstName: string; instructorLastName: string }) => chrome.tabs.Tab;
 }

src/shared/messages/TabManagementMessages.ts

@@ -4,17 +4,22 @@
 export default interface TabManagementMessages {
     /**
      * Opens a new tab with the given URL
-     * @param data The URL to open
+     *
+     * @param data - The URL to open
      */
     openNewTab: (data: { url: string }) => chrome.tabs.Tab;
+
     /**
      * Gets the ID of the current tab (the tab that sent the message)
+     *
      * @returns The ID of the current tab
      */
     getTabId: () => number;
+
     /**
      * Removes the tab with the given ID
-     * @param data The ID of the tab to remove
+     *
+     * @param data - The ID of the tab to remove
      * @returns The ID of the tab that was removed
      */
     removeTab: (data: { tabId: number }) => void;

src/shared/messages/UserScheduleMessages.ts

@@ -6,48 +6,61 @@ import type { Course } from '@shared/types/Course';
 export interface UserScheduleMessages {
     /**
      * Add a course to a schedule
-     * @param data the schedule id and course to add
+     *
+     * @param data - The schedule id and course to add
      */
     addCourse: (data: { scheduleId: string; course: Course }) => void;
+
     /**
      * Adds a course by URL
-     * @param data
+     *
+     * @param data - The URL of the course to add
      * @returns Response of the requested course URL
      */
     addCourseByURL: (data: { url: string; method: string; body?: string; response: 'json' | 'text' }) => string;
+
     /**
      * Remove a course from a schedule
-     * @param data the schedule id and course to remove
+     *
+     * @param data - The schedule id and course to remove
      */
     removeCourse: (data: { scheduleId: string; course: Course }) => void;
+
     /**
      * Clears all courses from a schedule
-     * @param data the id of the schedule to clear
+     *
+     * @param data - The id of the schedule to clear
      */
     clearCourses: (data: { scheduleId: string }) => void;
 
     /**
      * Switches the active schedule to the one specified
-     * @param data the id of the schedule to switch to
+     *
+     * @param data - The id of the schedule to switch to
      */
     switchSchedule: (data: { scheduleId: string }) => void;
 
     /**
      * Creates a new schedule with the specified name
-     * @param data the name of the schedule to create
-     * @returns undefined if successful, otherwise an error message
+     *
+     * @param data - The name of the schedule to create
+     * @returns Undefined if successful, otherwise an error message
      */
     createSchedule: (data: { scheduleName: string }) => string | undefined;
+
     /**
      * Deletes a schedule with the specified name
-     * @param data the id of the schedule to delete
-     * @returns undefined if successful, otherwise an error message
+     *
+     * @param data - The id of the schedule to delete
+     * @returns Undefined if successful, otherwise an error message
      */
     deleteSchedule: (data: { scheduleId: string }) => string | undefined;
+
     /**
      * Renames a schedule with the specified name
-     * @param data the id of the schedule to rename and the new name
-     * @returns undefined if successful, otherwise an error message
+     *
+     * @param data - The id of the schedule to rename and the new name
+     * @returns Undefined if successful, otherwise an error message
      */
     renameSchedule: (data: { scheduleId: string; newName: string }) => string | undefined;
 }

src/shared/storage/OptionsStore.ts

@@ -30,7 +30,8 @@ export const OptionsStore = createSyncStore<IOptionsStore>({
 
 /**
  * Initializes the settings by retrieving the values from the OptionsStore.
- * @returns {Promise<IOptionsStore>} A promise that resolves to an object satisfying the IOptionsStore interface.
+ *
+ * @returns A promise that resolves to an object satisfying the IOptionsStore interface.
  */
 export const initSettings = async () =>
     ({

src/shared/types/CachedData.ts

@@ -1,6 +1,5 @@
 /**
  * Represents cached data with its fetch timestamp
- * @template T The type of the cached data
  */
 export type CachedData<T> = {
     data: T;

src/shared/types/Course.ts

@@ -95,8 +95,9 @@ export class Course {
 
     /**
      * Gets a list of all the conflicts between this course and another course (i.e. if they have a meeting at the same time)
-     * @param other another course to compare this course to
-     * @returns a list of all the conflicts between this course and the other course as a tuple of the two conflicting meetings
+     *
+     * @param other - Another course to compare this course to
+     * @returns A list of all the conflicts between this course and the other course as a tuple of the two conflicting meetings
      */
     getConflicts(other: Course): [CourseMeeting, CourseMeeting][] {
         const conflicts: [CourseMeeting, CourseMeeting][] = [];

src/shared/types/CourseMeeting.ts

@@ -48,9 +48,10 @@ export class CourseMeeting {
 
     /**
      * Whether or not this meeting conflicts with another meeting
-     * MWF 10:00 am - 11:00 am conflicts with a F 10:00 am - 10:30 am
-     * @param meeting the meeting to check for conflicts with
-     * @returns true if the given meeting conflicts with this meeting, false otherwise
+     *
+     * @remarks MWF 10:00 am - 11:00 am conflicts with a F 10:00 am - 10:30 am
+     * @param meeting - The meeting to check for conflicts with
+     * @returns True if the given meeting conflicts with this meeting, false otherwise
      */
     isConflicting(meeting: CourseMeeting): boolean {
         const { days, startTime, endTime } = this;
@@ -64,8 +65,9 @@ export class CourseMeeting {
 
     /**
      * Return the string representation of the days of the week that this meeting is taught
-     * @param options options for the string representation
-     * @returns string representation of the days of the week that this meeting is taught
+     *
+     * @param options - Options for the string representation
+     * @returns String representation of the days of the week that this meeting is taught
      */
     getDaysString(options: DaysStringOptions): string {
         let { format, separator } = options;
@@ -86,8 +88,9 @@ export class CourseMeeting {
 
     /**
      * Return the string representation of the time range for the course
-     * @param options options for the string representation
-     * @returns string representation of the time range for the course
+     *
+     * @param options - Options for the string representation
+     * @returns String representation of the time range for the course
      */
     getTimeString(options: TimeStringOptions): string {
         const { startTime, endTime } = this;

src/shared/types/CourseSchedule.ts

@@ -20,9 +20,10 @@ export class CourseSchedule {
 
     /**
      * Given a string representation of the meeting information for a class, parse it into a CourseMeeting object
-     * @param dayLine a string representation of the days of the week that the course is taught: MWF, TR, etc.
-     * @param timeLine a string representation of a time-range that the course is taught: 10:00 am - 11:00 am, 1:00 pm - 2:00 pm, etc.
-     * @param locLine a string representation of the location that the course is taught in: JGB 2.302, etc.
+     *
+     * @param dayLine - A string representation of the days of the week that the course is taught: MWF, TR, etc.
+     * @param timeLine - A string representation of a time-range that the course is taught: 10:00 am - 11:00 am, 1:00 pm - 2:00 pm, etc.
+     * @param locLine - A string representation of the location that the course is taught in: JGB 2.302, etc.
      * @returns CourseMeeting object representing the meeting information
      */
     static parse(dayLine: string, timeLine: string, locLine: string): CourseMeeting {

src/shared/types/Instructor.ts

@@ -18,7 +18,8 @@ export default class Instructor {
 
     /**
      * Get the URL to the instructor's directory page on the UT Directory website
-     * @returns a URL string to the instructor's directory page
+     *
+     * @returns A URL string to the instructor's directory page
      */
     getDirectoryUrl(): string {
         const name = this.toString({
@@ -36,8 +37,9 @@ export default class Instructor {
 
     /**
      * Get a string representation of the instructor
-     * @param options the options for how to format the instructor string
-     * @returns a string representation of the instructor
+     *
+     * @param options - The options for how to format the instructor string
+     * @returns A string representation of the instructor
      */
     toString(options: InstructorFormatOptions): string {
         const { firstName, lastName, fullName } = this;

src/shared/util/colors.ts

@@ -33,7 +33,9 @@ export const useableColorways = Object.keys(theme.colors)
 
 /**
  * Generate a Tailwind classname for the font color based on the background color
- * @param bgColor the hex color of the background
+ *
+ * @param bgColor - The hex color of the background
+ * @returns The Tailwind classname for the font color
  */
 export function pickFontColor(bgColor: HexColor): 'text-white' | 'text-black' | 'text-theme-black' {
     const coefficients = [0.2126729, 0.7151522, 0.072175] as const;
@@ -56,7 +58,11 @@ export function pickFontColor(bgColor: HexColor): 'text-white' | 'text-black' |
 
 /**
  * Get primary and secondary colors from a Tailwind colorway
- * @param colorway the Tailwind colorway ex. "emerald"
+ *
+ * @param colorway - The Tailwind colorway ex. "emerald"
+ * @param index - The index of the primary color in the colorway
+ * @param offset - The offset to get the secondary color
+ * @returns The primary and secondary colors
  */
 export function getCourseColors(colorway: TWColorway, index?: number, offset: number = 300): CourseColors {
     if (index === undefined) {
@@ -117,8 +123,12 @@ export function getColorwayFromColor(color: HexColor): TWColorway {
 
 /**
  * Get next unused color in a tailwind colorway for a given schedule
- * @param schedule the schedule which the course is in
- * @param course the course to get the color for
+ *
+ * @param schedule - The schedule which the course is in
+ * @param course - The course to get the color for
+ * @param index - The index of the primary color in the colorway
+ * @param offset - The offset to get the secondary color
+ * @returns The primary and secondary colors
  */
 export function getUnusedColor(
     schedule: Serialized<UserSchedule>,
@@ -221,8 +231,9 @@ function rgbToSrgb(rgb: RGB): sRGB {
 
 /**
  * Convert an RGB color to the OKLab color space
- * @param rgb the RGB color
- * @returns the color in the OKLab color space
+ *
+ * @param rgb - The RGB color
+ * @returns The color in the OKLab color space
  */
 function srgbToOKlab([r, g, b]: sRGB): Lab {
     let l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;

src/shared/util/downloadBlob.ts

@@ -3,9 +3,10 @@ import MIMEType from '../types/MIMEType';
 
 /**
  * Downloads a blob by creating a temporary URL and triggering a download.
- * @param blobPart The blob data to be downloaded.
- * @param type The MIME type of the blob.
- * @param fileName The name of the file to be downloaded.
+ *
+ * @param blobPart - The blob data to be downloaded.
+ * @param type - The MIME type of the blob.
+ * @param fileName - The name of the file to be downloaded.
  * @returns A promise that resolves when the download is successful, or rejects with an error if the download fails.
  */
 export function downloadBlob(blobPart: BlobPart, type: MIMETypeKey, fileName: string): Promise<void> {

src/shared/util/icons.tsx

@@ -7,12 +7,17 @@ import ClosedIcon from '~icons/material-symbols/lock';
 import WaitlistIcon from '~icons/material-symbols/timelapse';
 import CancelledIcon from '~icons/material-symbols/warning';
 
+interface StatusIconProps extends SVGProps<SVGSVGElement> {
+    status: StatusType;
+}
+
 /**
  * Get Icon component based on status
- * @param props.status status
- * @returns the icon component
+ *
+ * @param props - The props for the StatusIcon component
+ * @returns The rendered icon component
  */
-export function StatusIcon(props: SVGProps<SVGSVGElement> & { status: StatusType }): JSX.Element | null {
+export function StatusIcon(props: StatusIconProps): JSX.Element | null {
     const { status, ...rest } = props;
 
     switch (status) {

src/shared/util/random.ts

@@ -3,7 +3,7 @@ import { customAlphabet } from 'nanoid';
 /**
  * Generate secure URL-friendly unique ID.
  *
- * @param size Size of the ID. The default size is 12.
+ * @param size - Size of the ID. The default size is 12.
  * @returns A random string.
  */
 export const generateRandomId = customAlphabet('abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789', 12);

src/shared/util/string.ts

@@ -1,6 +1,7 @@
 /**
  * Given a string, returns a string with the first letter capitalized.
- * @input The string to capitalize.
+ *
+ * @param input - The string to capitalize.
  */
 export function capitalize(input: string): string {
     let capitalized = '';
@@ -25,8 +26,9 @@ export function capitalize(input: string): string {
 
 /**
  * Given a string, returns a string with the first letter capitalized.
- * @param input capitalize the first letter of this string
- * @returns the string with the first letter capitalized
+ *
+ * @param input - Capitalize the first letter of this string
+ * @returns The string with the first letter capitalized
  */
 export function capitalizeFirstLetter(input: string): string {
     return input.charAt(0).toUpperCase() + input.slice(1).toLowerCase();
@@ -34,8 +36,9 @@ export function capitalizeFirstLetter(input: string): string {
 
 /**
  * Cuts the input string to the specified length and adds an ellipsis if the string is longer than the specified length.
- * @param input The string to ellipsify.
- * @param length The length of the string to return.
+ *
+ * @param input - The string to ellipsify.
+ * @param length - The length of the string to return.
  * @returns The ellipsified string.
  */
 export const ellipsify = (input: string, chars: number): string => {

src/shared/util/time.ts

@@ -6,6 +6,7 @@ export const DAY = 24 * HOUR;
 
 /**
  * Pauses the execution for the specified number of milliseconds.
+ *
  * @param milliseconds - The number of milliseconds to sleep.
  * @returns A promise that resolves after the specified number of milliseconds.
  */
@@ -14,8 +15,8 @@ export const sleep = (milliseconds: number): Promise<void> => new Promise(resolv
 /**
  * Checks to see if expired by the time first stored and the time frame that it is stored for
  *
- * @param time time it was stored
- * @param threshold time frame it can be stored for
- * @return true if expired, false if the time frame is still in range
+ * @param time - time it was stored
+ * @param threshold - time frame it can be stored for
+ * @returns true if expired, false if the time frame is still in range
  */
 export const didExpire = (time: number, threshold: number): boolean => time + threshold <= Date.now();