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/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();