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/lib/CourseCatalogScraper.ts

@@ -46,8 +46,9 @@ export class CourseCatalogScraper {
 
     /**
      * Pass in a list of HTMLtable rows and scrape every course from them
-     * @param rows the rows of the course catalog table
-     * @param keepHeaders whether to keep the header rows (which contain the course name) in the output
+     *
+     * @param rows - the rows of the course catalog table
+     * @param keepHeaders - whether to keep the header rows (which contain the course name) in the output
      * @returns an array of course row objects (which contain courses corresponding to the htmltable row)
      */
     public scrape(rows: NodeListOf<HTMLTableRowElement> | HTMLTableRowElement[], keepHeaders = false): ScrapedRow[] {
@@ -109,8 +110,12 @@ export class CourseCatalogScraper {
 
     /**
      * Separate the course name into its department, number, and name
-     * @example separateCourseName("CS 314H - Honors Discrete Structures") => ["Honors Discrete Structures", "CS", "314H"]
-     * @param courseFullName the full name of the course (e.g. "CS 314H - Honors Discrete Structures")
+     *
+     * @example
+     * ```
+     * separateCourseName("CS 314H - Honors Discrete Structures") => ["Honors Discrete Structures", "CS", "314H"]
+     * ```
+     * @param courseFullName - the full name of the course (e.g. "CS 314H - Honors Discrete Structures")
      * @returns an array of the course name , department, and number
      */
     separateCourseName(courseFullName: string): [courseName: string, department: string, number: string] {
@@ -124,8 +129,9 @@ export class CourseCatalogScraper {
 
     /**
      * Gets how many credit hours the course is worth
-     * @param courseNumber the course number, CS 314H
-     * @return the number of credit hours the course is worth
+     *
+     * @param courseNumber - the course number, CS 314H
+     * @returns the number of credit hours the course is worth
      */
     getCreditHours(courseNumber: string): number {
         let creditHours = Number(courseNumber.split('')[0]);
@@ -149,7 +155,8 @@ export class CourseCatalogScraper {
 
     /**
      * Scrape the Unique ID from the course catalog table row
-     * @param row the row of the course catalog table
+     *
+     * @param row - the row of the course catalog table
      * @returns the uniqueid of the course as a number
      */
     getUniqueId(row: HTMLTableRowElement): number {
@@ -162,7 +169,8 @@ export class CourseCatalogScraper {
 
     /**
      * Scrapes the individual URL for a given course that takes you to the course details page
-     * @param row the row of the course catalog table
+     *
+     * @param row - the row of the course catalog table
      * @returns the url of the course details page for the course in the row
      */
     getURL(row: HTMLTableRowElement): string {
@@ -172,7 +180,8 @@ export class CourseCatalogScraper {
 
     /**
      * Scrape who is teaching the course from the course catalog table row with meta-data about their name
-     * @param row the row of the course catalog table
+     *
+     * @param row - the row of the course catalog table
      * @returns an array of instructors for the course
      */
     getInstructors(row: HTMLTableRowElement): Instructor[] {
@@ -197,7 +206,8 @@ export class CourseCatalogScraper {
 
     /**
      * Whether or not this is a header row for a course within the course catalog list (we can't scrape courses from header rows)
-     * @param row the row of the course catalog table
+     *
+     * @param row - the row of the course catalog table
      * @returns true if this is a header row, false otherwise
      */
     isHeaderRow(row: HTMLTableRowElement): boolean {
@@ -206,7 +216,8 @@ export class CourseCatalogScraper {
 
     /**
      * Scrape whether the class is being taught online, in person, or a hybrid of the two
-     * @param row the row of the course catalog table
+     *
+     * @param row - the row of the course catalog table
      * @returns the instruction mode of the course
      */
     getInstructionMode(row: HTMLTableRowElement): InstructionMode {
@@ -223,7 +234,8 @@ export class CourseCatalogScraper {
 
     /**
      * Scrapes the description of the course from the course details page and separates it into an array of cleaned up lines
-     * @param doc the document of the course details page to scrape
+     *
+     * @param doc - the document of the course details page to scrape
      * @returns an array of lines of the course description
      */
     getDescription(doc: Document): string[] {
@@ -273,7 +285,8 @@ export class CourseCatalogScraper {
 
     /**
      * Get the full name of the course from the course catalog table row (e.g. "CS 314H - Honors Discrete Structures")
-     * @param row the row of the course catalog table
+     *
+     * @param row - the row of the course catalog table
      * @returns the full name of the course
      */
     getFullName(row?: HTMLTableRowElement): string {
@@ -286,7 +299,8 @@ export class CourseCatalogScraper {
 
     /**
      * When registration is open, the registration URL will show up in the course catalog table row as a link. This will scrape it from the row.
-     * @param row the row of the course catalog table
+     *
+     * @param row - the row of the course catalog table
      * @returns the registration URL for the course if it is currently displayed, undefined otherwise
      */
     getRegisterURL(row: HTMLTableRowElement): string | undefined {
@@ -296,8 +310,9 @@ export class CourseCatalogScraper {
 
     /**
      * Scrapes whether the course is open, closed, waitlisted, or cancelled
-     * @param row the row of the course catalog table
-     * @returns
+     *
+     * @param row - the row of the course catalog table
+     * @returns a tuple of the status of the course and whether the course is reserved
      */
     getStatus(row: HTMLTableRowElement): [status: StatusType, isReserved: boolean] {
         const div = row.querySelector(TableDataSelector.STATUS);
@@ -327,7 +342,8 @@ export class CourseCatalogScraper {
 
     /**
      * At UT, some courses have certain "flags" which aid in graduation. This will scrape the flags from the course catalog table row.
-     * @param row
+     *
+     * @param row - the row of the course catalog table
      * @returns an array of flags for the course
      */
     getFlags(row: HTMLTableRowElement): string[] {
@@ -337,7 +353,8 @@ export class CourseCatalogScraper {
 
     /**
      * Get the list of core curriculum requirements the course satisfies
-     * @param row
+     *
+     * @param row - the row of the course catalog table
      * @returns an array of core curriculum codes
      */
     getCore(row: HTMLTableRowElement): string[] {
@@ -352,7 +369,8 @@ export class CourseCatalogScraper {
 
     /**
      * This will scrape all the time information from the course catalog table row and return it as a CourseSchedule object, which represents all of the meeting timiestimes/places of the course.
-     * @param row the row of the course catalog table
+     *
+     * @param row - the row of the course catalog table
      * @returns a CourseSchedule object representing all of the meetings of the course
      */
     getSchedule(row: HTMLTableRowElement): CourseSchedule {

src/views/lib/database/queryDistribution.ts

@@ -12,8 +12,9 @@ type GradeDistributionParams = {
 };
 
 /**
- * fetches the aggregate distribution of grades for a given course from the course db, and the semesters that we have data for
- * @param course the course to fetch the distribution for
+ * Fetches the aggregate distribution of grades for a given course from the course db, and the semesters that we have data for
+ *
+ * @param course - the course to fetch the distribution for
  * @returns a Distribution object containing the distribution of grades for the course, and
  * an array of semesters that we have the distribution for
  */
@@ -97,8 +98,9 @@ export async function queryAggregateDistribution(course: Course): Promise<[Distr
 
 /**
  * Creates a SQL query that we can execute on the database to get the distribution of grades for a given course in a given semester
- * @param course the course to fetch the distribution for
- * @param semester the semester to fetch the distribution for OR null if we want the aggregate distribution
+ *
+ * @param course - the course to fetch the distribution for
+ * @param semester - the semester to fetch the distribution for OR null if we want the aggregate distribution
  * @returns a SQL query string
  */
 function generateQuery(
@@ -131,9 +133,10 @@ function generateQuery(
 }
 
 /**
- * fetches the distribution of grades for a semester for a given course from the course db
- * @param course the course to fetch the distribution for
- * @param semester the semester to fetch the distribution for
+ * Fetches the distribution of grades for a semester for a given course from the course db
+ *
+ * @param course - the course to fetch the distribution for
+ * @param semester - the semester to fetch the distribution for
  * @returns a Distribution object containing the distribution of grades for the course
  */
 export async function querySemesterDistribution(course: Course, semester: Semester): Promise<[Distribution, boolean]> {

src/views/lib/getCourseTableRows.ts

@@ -2,7 +2,8 @@ const TABLE_ROW_SELECTOR = 'table tbody tr';
 
 /**
  * Returns an array of all the rows in the course table on the passed in document
- * @param doc the document to get the course table rows from
+ *
+ * @param doc - the document to get the course table rows from
  * @returns an array of all the rows in the course table on the passed in document
  */
 export default function getCourseTableRows(doc: Document): HTMLTableRowElement[] {

src/views/lib/getSiteSupport.ts

@@ -24,7 +24,8 @@ export type SiteSupportType = (typeof SiteSupport)[keyof typeof SiteSupport];
 
 /**
  * We use this function to determine what page the user is on, and then we can use that information to determine what to do
- * @param url the url of the current page
+ *
+ * @param url - the url of the current page
  * @returns a list of page types that the current page is
  */
 export default function getSiteSupport(url: string): SiteSupportType | null {

src/views/lib/getUpdatedAtDateTimeString.ts

@@ -1,7 +1,8 @@
 /**
+ * Returns a formatted string of the last time the schedule was updated.
  *
- * @param updatedAt {number} - The time in milliseconds since the epoch when the schedule was last updated.
- * @returns {string} - DateTime formatted as HH:MM AM/PM MM/DD/YYYY
+ * @param updatedAt - The time in milliseconds since the epoch when the schedule was last updated.
+ * @returns DateTime formatted as HH:MM AM/PM MM/DD/YYYY
  */
 export function getUpdatedAtDateTimeString(updatedAt: number): string {
     const updatedAtDate = new Date(updatedAt);

src/views/lib/loadNextCourseCatalogPage.ts

@@ -25,6 +25,7 @@ let nextPageURL = getNextButton(document)?.href;
 /**
  * This will scrape the pagination buttons from the course list and use them to load the next page
  * and then return the table rows from the next page
+ *
  * @returns a tuple of the current LoadStatus (whether are currently loading the next page, or if we have reached the end of the course catalog,
  * or if there was an error loading the next page) and an array of the table rows from the next page (or an empty array
  * if we have reached the end of the course catalog
@@ -67,7 +68,8 @@ export async function loadNextCourseCatalogPage(): Promise<[AutoLoadStatusType,
 
 /**
  * Scrapes the next button from the document
- * @param doc  the document to get the next button from
+ *
+ * @param doc - the document to get the next button from
  * @returns the next button from the document
  */
 export function getNextButton(doc: Document) {
@@ -76,7 +78,8 @@ export function getNextButton(doc: Document) {
 
 /**
  * Removes the next and previous buttons from the document so that we don't load the same page twice
- * @param doc the document to remove the next and previous buttons from
+ *
+ * @param doc - the document to remove the next and previous buttons from
  */
 export function removePaginationButtons(doc: Document) {
     const nextButton = doc.querySelectorAll<HTMLAnchorElement>(NEXT_PAGE_BUTTON_SELECTOR);