JSDoc Updates

eslint.config.mjs

@@ -5,16 +5,17 @@ import pluginReact from "eslint-plugin-react";
 import css from "@eslint/css";
 import { defineConfig } from "eslint/config";
 import stylistic from "@stylistic/eslint-plugin";
+import jsdoc from "eslint-plugin-jsdoc";
 
 export default defineConfig([
     { settings: { react: { version: "detect" } } },
     { ignores: ["*.cjs", "eslint.config.mjs", "**/public/**", "**/node_modules/**", "**/cypress/**", "cypress.config.ts", ".stylelintrc.js", "src/frontend/testing/**", "src/frontend/css/stylesheets/external/**", "src/frontend/components/dashboard/lib/react/polyfills/**", "babel.config.js", "webpack.config.js", "jest.config.js", "tsconfig.json", "src/frontend/js/lib/jqplot/**", "src/frontend/js/lib/jquery/**", "src/frontend/js/lib/plotly/**", "src/frontend/components/timeline/**", "fengari-web.js"] },
     { files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"], plugins: { js }, extends: ["js/recommended"] },
-    { files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"], languageOptions: { globals: { ...globals.browser, ...globals.jquery } } },
+    { files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"], languageOptions: { globals: { ...globals.browser, ...globals.jquery, ...globals.jest } } },
     tseslint.configs.recommended,
     pluginReact.configs.flat.recommended,
     { files: ["**/*.css"], plugins: { css }, language: "css/css", extends: ["css/recommended"] },
-    { plugins: {'@stylistic': stylistic} },
+    { plugins: {'@stylistic': stylistic, jsdoc} },
     {
         rules: {
             "@typescript-eslint/no-explicit-any": "off",
@@ -25,7 +26,19 @@ export default defineConfig([
             '@stylistic/semi': ['error', 'always'],
             '@stylistic/curly-newline': 'error',
             '@stylistic/indent': ['error', 4],
-            '@stylistic/comma-dangle': ['error', 'never']
+            '@stylistic/comma-dangle': ['error', 'never'],
+            "jsdoc/require-jsdoc": [
+                "error",
+                {
+                    require: {
+                        FunctionDeclaration: true,
+                        MethodDefinition: true,
+                        ClassDeclaration: true,
+                        ArrowFunctionExpression: false,
+                        FunctionExpression: false
+                    }
+                }
+            ],
         }
     }
 ]);

package.json

@@ -78,6 +78,7 @@
     "css-loader": "^3.2.0",
     "cypress": "^13.7.2",
     "eslint": "^9.31.0",
+    "eslint-plugin-jsdoc": "^52.0.0",
     "eslint-plugin-react": "^7.37.5",
     "globals": "^16.3.0",
     "jest": "^29.7.0",

src/frontend/components/alert/lib/alertBase.ts

@@ -1,6 +1,9 @@
 import { Hidable, Renderable } from 'util/renderable';
 import { AlertType } from './types';
 
+/**
+ * Base class for alert components that can be rendered to the DOM and hidden when necessary.
+ */
 export abstract class AlertBase extends Hidable implements Renderable<HTMLDivElement> {
     /**
      * Create an instance of AlertBase.

src/frontend/components/alert/lib/dangerAlert.ts

@@ -1,5 +1,8 @@
-import { AlertBase } from "./alertBase";
+import { AlertBase } from './alertBase';
 
+/**
+ * Class representing a danger alert.
+ */
 export class DangerAlert extends AlertBase {
     /**
      * Create an instance of InfoAlert.

src/frontend/components/alert/lib/infoAlert.ts

@@ -1,17 +1,19 @@
 import { AlertBase } from './alertBase';
 
+/**
+ * InfoAlert class represents an informational alert in the application.
+ */
 export class InfoAlert extends AlertBase {
     /**
      * Create an instance of InfoAlert.
      * This class extends AlertBase to provide a specific implementation for info alerts.
-     * It uses the AlertType.INFO to set the alert type.
      * @class
      * @public
      * @memberof alert.lib
      * @constructor
      * @param {string} message - The message to be displayed in the info alert.
      */
     constructor(message: string) {
-        super(message, "info");
+        super(message, 'info');
     }
-}
+}

src/frontend/components/alert/lib/successAlert.ts

@@ -1,5 +1,8 @@
-import { AlertBase } from "./alertBase";
+import { AlertBase } from './alertBase';
 
+/**
+ * Class representing a success alert.
+*/
 export class SuccessAlert extends AlertBase {
     /**
      * Create an instance of InfoAlert.

src/frontend/components/alert/lib/warningAlert.ts

@@ -1,17 +1,19 @@
-import { AlertBase } from "./alertBase";
+import { AlertBase } from './alertBase';
 
+/**
+ * Class representing a warning alert. This class extends AlertBase to provide a specific implementation for warning alerts.
+ */
 export class WarningAlert extends AlertBase {
     /**
      * Create an instance of InfoAlert.
      * This class extends AlertBase to provide a specific implementation for info alerts.
-     * It uses the AlertType.INFO to set the alert type.
      * @class
      * @public
      * @memberof alert.lib
      * @constructor
      * @param {string} message - The message to be displayed in the info alert.
      */
     constructor(message: string) {
-        super(message, "warning");
+        super(message, 'warning');
     }
 }

src/frontend/components/button/lib/RenderableButton.ts

@@ -1,18 +1,31 @@
-import { Renderable } from "util/renderable";
+import { Renderable } from 'util/renderable';
 
+/**
+ * A simple button component that can be rendered to the DOM. It takes a text, an onClick handler, and an optional list of CSS classes.
+ */
 export class RenderableButton implements Renderable<HTMLButtonElement> {
     classList: string[] = [];
 
+    /**
+     * Creates a new RenderableButton instance.
+     * @param text The text to display in the button
+     * @param onClick The onclick listener for when the button is clicked
+     * @param classList Any classes to add to the button
+     */
     constructor(private readonly text: string, private readonly onClick: (ev: MouseEvent)=>void, ...classList: string[]) {
         this.classList = classList;
     }
 
+    /**
+     * Renders the button to an HTMLButtonElement.
+     * @returns A button element to attach to the DOM
+     */
     render(): HTMLButtonElement {
         const button = document.createElement('button');
         button.textContent = this.text;
         button.addEventListener('click', this.onClick);
         button.classList.add(...this.classList, 'btn');
-        const btnType = this.classList.find(b=>b.startsWith('btn-')) ? '' : 'btn-default'
+        const btnType = this.classList.find(b=>b.startsWith('btn-')) ? '' : 'btn-default';
         if(btnType) {
             button.classList.add(btnType);
         }

src/frontend/components/button/lib/cancel-button.ts

@@ -1,5 +1,10 @@
 import { clearSavedFormValues } from './common';
 
+/**
+ * Create a cancel button that navigates away from the page
+ * This component will navigate away to the parameter defined in the data-href attribute, or will navigate back
+ * @param { HTMLElement | JQuery<HTMLElement> } el The button element
+ */
 export default function createCancelButton(el: HTMLElement | JQuery<HTMLElement>) {
     const $el = $(el);
     if ($el[0].tagName !== 'BUTTON') return;
@@ -12,4 +17,4 @@ export default function createCancelButton(el: HTMLElement | JQuery<HTMLElement>
         else
             window.history.back();
     });
-}
+}

src/frontend/components/button/lib/common.test.ts

@@ -1,3 +1,4 @@
+import { describe, it, expect } from '@jest/globals';
 import { layoutId, recordId, table_key } from './common';
 
 describe('Common button tests', () => {

src/frontend/components/button/lib/common.ts

@@ -2,7 +2,6 @@ import StorageProvider from 'util/storageProvider';
 
 /**
  * Clear all saved form values for the current record
- * @param $form The form to clear the data for
  */
 export async function clearSavedFormValues() {
     const ls = storage();
@@ -13,33 +12,33 @@ export async function clearSavedFormValues() {
 
 /**
  * Get the layout identifier from the body data
- * @returns The layout identifier
+ * @returns { number } The layout identifier
  */
-export function layoutId() {
+export function layoutId(): number {
     return $('body').data('layout-identifier');
 }
 
 /**
  * Get the record identifier from the body data
- * @returns The record identifier
+ * @returns { number } The record identifier
  */
-export function recordId() {
+export function recordId(): number {
     return $('body').find('.form-edit')
         .data('current-id') || 0;
 }
 
 /**
  * Get the key for the table used for saving form values
- * @returns The key for the table
+ * @returns {string} The key for the table
  */
-export function table_key() {
+export function table_key(): string {
     return `linkspace-record-change-${layoutId()}-${recordId()}`;
 }
 
 /**
  * Get the storage object - this originally was used in debugging to allow for the storage object to be mocked
- * @returns The storage object
+ * @returns { StorageProvider } The storage object
  */
-export function storage() {
+export function storage(): StorageProvider {
     return new StorageProvider(table_key());
-}
+}

src/frontend/components/button/lib/component.test.ts

@@ -1,3 +1,4 @@
+import { describe, it, expect } from '@jest/globals';
 import ButtonComponent from './component';
 
 describe('Button Component', () => {

src/frontend/components/button/lib/component.ts

@@ -2,7 +2,6 @@ import {Component} from 'component';
 
 /**
  * Button component
- * @extends Component
  */
 class ButtonComponent extends Component {
     /**
@@ -19,6 +18,7 @@ class ButtonComponent extends Component {
 
     /**
      * Get the map of button components
+     * @returns {Map<string, (element: JQuery<HTMLElement>) => void>} The map of button components
      */
     private get buttonsMap(): Map<string, (element: JQuery<HTMLElement>) => void> {
         if (!ButtonComponent.staticButtonsMap) ButtonComponent.initMap();
@@ -27,7 +27,7 @@ class ButtonComponent extends Component {
 
     /**
      * Create a button component
-     * @param element {HTMLElement} The button element
+     * @param { HTMLElement } element The button element
      */
     constructor(element: HTMLElement) {
         super(element);
@@ -116,7 +116,7 @@ class ButtonComponent extends Component {
 
     /**
      * Initialize the button
-     * @param element {HTMLElement} The button element
+     * @param {HTMLElement} element The button element
      */
     private initButton(element: HTMLElement) {
         const el: JQuery<HTMLElement> = $(element);

src/frontend/components/button/lib/create-report-button.test.ts

@@ -1,6 +1,6 @@
 import { validateRequiredFields } from 'validation';
 import CreateReportButtonComponent from './create-report-button';
-import { describe, it, expect } from '@jest/globals';
+import { describe, it, expect, jest } from '@jest/globals';
 
 describe('create-report-button', () => {
     it('does not submit form if no checkboxes are checked', () => {

src/frontend/components/button/lib/delete-button.ts

@@ -1,10 +1,8 @@
-// noinspection ExceptionCaughtLocallyJS
-
 import { logging } from 'logging';
 
 /**
  * Create delete button
- * @param element {JQuery<HTMLElement>} - Element to act as a delete button
+ * @param {JQuery<HTMLElement>} element Element to act as a delete button
  */
 export default function createDeleteButton(element: JQuery<HTMLElement>) {
     element.on('click', (ev) => {

src/frontend/components/button/lib/remove-curval-button.ts

@@ -1,6 +1,6 @@
 /**
  * Create remove curval button
- * @param element {JQuery<HTMLElement>} - The element to function as a remove curval button
+ * @param {JQuery<HTMLElement>} element The element to function as a remove curval button
  */
 export default function createRemoveCurvalButton(element: JQuery<HTMLElement>) {
     element.on('click', (ev: JQuery.ClickEvent) => {

src/frontend/components/button/lib/remove-unload-button.ts

@@ -1,6 +1,6 @@
 /**
  * Create a button that removes the unload event listener
- * @param element {JQuery<HTMLElement>} - The button element to add the click event to
+ * @param {JQuery<HTMLElement>} element The button element to add the click event to
  */
 export default function createRemoveUnloadButton(element: JQuery<HTMLElement>) {
     element.on('click', () => {

src/frontend/components/button/lib/rename-button.ts

@@ -170,6 +170,11 @@ class RenameButton {
         this.hideRenameControls(id, button);
     }
 
+    /**
+     * Hides the rename controls
+     * @param {number} id The id of the field
+     * @param {JQuery<HTMLButtonElement>} button The button that was clicked
+     */
     private hideRenameControls(id: number, button: JQuery<HTMLButtonElement>) {
         $(`#current-${id}`).removeClass('hidden')
             .attr('aria-hidden', 'false');

src/frontend/components/button/lib/save-view-button.ts

@@ -2,7 +2,8 @@ import { validateRequiredFields } from 'validation';
 import '@lol768/jquery-querybuilder-no-eval';
 
 /**
- * SaveViewButtonComponent
+ * Button component for saving views for an instance.
+ * @param {JQuery<HTMLElement>} el The jQuery element that represents the Save View button.
  */
 export default function createSaveViewButtonComponent(el: JQuery<HTMLElement>) {
     const $form = el.closest('form');
@@ -34,4 +35,4 @@ export default function createSaveViewButtonComponent(el: JQuery<HTMLElement>) {
                 .val(JSON.stringify(res, null, 2));
         });
     });
-}
+}

src/frontend/components/button/lib/show-blank-button.ts

@@ -1,6 +1,6 @@
 /**
  * Create a button that toggles the visibility of blank fields.
- * @param element {JQuery<HTMLElement>} The element to attach the button to.
+ * @param {JQuery<HTMLElement>} element The element to attach the button to.
  */
 export default function createShowBlankButton(element: JQuery<HTMLElement>) {
     element.on('click', (ev) => {
@@ -14,4 +14,4 @@ export default function createShowBlankButton(element: JQuery<HTMLElement>) {
             ? 'Hide blank values'
             : 'Show blank values';
     });
-}
+}

src/frontend/components/button/lib/submit-draft-record-button.ts

@@ -2,7 +2,7 @@ import { clearSavedFormValues } from './common';
 
 /**
  * Create a submit draft record button
- * @param element {JQuery<HTMLElement>} The button element
+ * @param {JQuery<HTMLElement>} element The button element
  */
 export default function createSubmitDraftRecordButton(element: JQuery<HTMLElement>) {
     element.on('click', async (ev: JQuery.ClickEvent) => {

src/frontend/components/button/lib/submit-field-button.test.ts

@@ -1,3 +1,7 @@
+import { describe, it, expect, beforeEach } from '@jest/globals';
+/* eslint-disable jsdoc/require-jsdoc */
+/* eslint-disable @typescript-eslint/ban-ts-comment */
+/* @ts-ignore */
 import { initGlobals } from 'testing/globals.definitions';
 import SubmitFieldButtonComponent from './submit-field-button';
 
@@ -36,4 +40,4 @@ describe('Submit field button tests', () => {
         expect($.ajax).toHaveBeenCalled();
         expect(window.alert).toHaveBeenCalled();
     });
-});
+});