Merge pull request #390 from neilenns/neilenns/issue364

Clean up code comments on controllers

src/actions/stationStatus.ts

@@ -9,8 +9,8 @@ import {
   WillAppearEvent,
   WillDisappearEvent,
 } from "@elgato/streamdeck";
-import { handleAddStation } from "@events/streamDeck/stationStatus/addStation";
 import { handleRemove } from "@events/streamDeck/remove";
+import { handleAddStation } from "@events/streamDeck/stationStatus/addStation";
 import { handleStationStatusLongPress } from "@events/streamDeck/stationStatus/stationStatusLongPress";
 import { handleStationStatusShortPress } from "@events/streamDeck/stationStatus/stationStatusShortPress";
 import { handleUpdateStation } from "@events/streamDeck/stationStatus/updateStation";
@@ -21,18 +21,21 @@ import debounce from "debounce";
 /**
  * Represents the status of a TrackAudio station
  */
-export class StationStatus extends SingletonAction<StationSettings> {
+export class StationStatus extends SingletonAction<StationStatusSettings> {
   private _keyDownStart = 0;
 
-  debouncedUpdate = debounce((action: KeyAction, settings: StationSettings) => {
-    handleUpdateStation(action, settings);
-  }, 300);
+  debouncedUpdate = debounce(
+    (action: KeyAction, settings: StationStatusSettings) => {
+      handleUpdateStation(action, settings);
+    },
+    300
+  );
 
   // When the action is added to a profile it gets saved in the ActionManager
   // instance for use elsewhere in the code. The default title is also set
   // to something useful.
   override onWillAppear(
-    ev: WillAppearEvent<StationSettings>
+    ev: WillAppearEvent<StationStatusSettings>
   ): void | Promise<void> {
     // This should never happen. Typeguard to ensure the rest of the code can just use
     // KeyAction.
@@ -45,15 +48,15 @@ export class StationStatus extends SingletonAction<StationSettings> {
 
   // When the action is removed from a profile it also gets removed from the ActionManager.
   override onWillDisappear(
-    ev: WillDisappearEvent<StationSettings>
+    ev: WillDisappearEvent<StationStatusSettings>
   ): void | Promise<void> {
     handleRemove(ev.action);
   }
 
   // When settings are received the ActionManager is called to update the existing
   // settings on the saved action.
   override onDidReceiveSettings(
-    ev: DidReceiveSettingsEvent<StationSettings>
+    ev: DidReceiveSettingsEvent<StationStatusSettings>
   ): void | Promise<void> {
     // This should never happen. Typeguard to ensure the rest of the code can just use
     // KeyAction.
@@ -68,7 +71,9 @@ export class StationStatus extends SingletonAction<StationSettings> {
     this._keyDownStart = Date.now();
   }
 
-  override onKeyUp(ev: KeyUpEvent<StationSettings>): Promise<void> | void {
+  override onKeyUp(
+    ev: KeyUpEvent<StationStatusSettings>
+  ): Promise<void> | void {
     const pressLength = Date.now() - this._keyDownStart;
 
     if (pressLength > LONG_PRESS_THRESHOLD) {
@@ -79,8 +84,9 @@ export class StationStatus extends SingletonAction<StationSettings> {
   }
 }
 
-export interface StationSettings {
+export interface StationStatusSettings {
   autoSetListen?: boolean;
+  autoSetSpk?: boolean;
   autoSetRx?: boolean;
   blockedCommsImagePath?: string;
   activeCommsImagePath?: string;

src/controllers/atisLetter.ts

@@ -3,9 +3,9 @@ import { KeyAction } from "@elgato/streamdeck";
 import { Controller } from "@interfaces/controller";
 import TitleBuilder from "@root/utils/titleBuilder";
 import { stringOrUndefined } from "@root/utils/utils";
-import { BaseController } from "./baseController";
-import debounce from "debounce";
 import { ATIS_LETTER_CONTROLLER_TYPE } from "@utils/controllerTypes";
+import debounce from "debounce";
+import { BaseController } from "./baseController";
 
 const defaultTemplatePath = "images/actions/atisLetter/template.svg";
 
@@ -38,14 +38,15 @@ export class AtisLetterController extends BaseController {
 
   /**
    * Refreshes the title and image on the action.
+   * @remarks This method is debounced with a 100ms delay to prevent excessive updates.
    */
   public override refreshDisplay = debounce(() => {
     this.refreshTitle();
     this.refreshImage();
   });
 
   /**
-   * Resets the action to its default, disconnected, state.
+   * Resets the action to its default state.
    */
   public reset() {
     this._letter = undefined;
@@ -57,16 +58,18 @@ export class AtisLetterController extends BaseController {
 
   //#region Getters and setters
   /**
-   * Gets the autoClear setting, returning true as default if it wasn't set.
+   * Gets the autoClear setting.
+   * @returns {boolean} True if auto clear is enabled. Defaults to true.
    */
-  get autoClear() {
+  get autoClear(): boolean {
     return this.settings.autoClear ?? true;
   }
 
   /**
-   * Gets isUnavailable, which is true if no ATIS letter was available in the last VATSIM update.
+   * Gets isUnavailable.
+   * @returns {boolean} True if no ATIS letter is available for the station.
    */
-  get isUnavailable() {
+  get isUnavailable(): boolean {
     return this._isUnavailable;
   }
 
@@ -84,75 +87,79 @@ export class AtisLetterController extends BaseController {
   }
 
   /**
-   * Returns the callsign for the ATIS action.
+   * Gets the callsign value from settings.
+   * @returns {string | undefined} The callsign. Defaults to undefined.
    */
-  get callsign() {
+  get callsign(): string | undefined {
     return this.settings.callsign;
   }
 
   /**
-   * Returns the currentImagePath or the default template path if the
-   * user didn't specify a custom icon.
+   * Gets the path to the current image template.
+   * @returns {string} The path specified by the user, or the defaultTemplatePath if none was specified.
    */
   get currentImagePath(): string {
     return this._currentImagePath ?? defaultTemplatePath;
   }
 
   /**
-   * Sets the currentImagePath and re-compiles the SVG template if necessary.
+   * Sets the currentImagePath.
    */
   set currentImagePath(newValue: string | undefined) {
     this._currentImagePath = stringOrUndefined(newValue);
   }
 
   /**
-   * Returns the updatedImagePath or the default template path if the user
-   * didn't specify a custom icon.
+   * Gets the path to the updated image template.
+   * @returns {string} The path specified by the user, or the defaultTemplatePath if none was specified.
    */
   get updatedImagePath(): string {
     return this._updatedImagePath ?? defaultTemplatePath;
   }
 
   /**
-   * Sets the updatedImagePath and re-compiles the SVG template if necessary.
+   * Sets the updatedImagePath.
    */
   set updatedImagePath(newValue: string | undefined) {
     this._updatedImagePath = stringOrUndefined(newValue);
   }
 
   /**
-   * Returns the unavailableImagePath or the default unavailable template path
-   * if the user didn't specify a custom icon.
+   * Gets the path to the unavailable image template.
+   * @returns {string} The path specified by the user, or the defaultTemplatePath if none was specified.
    */
   get unavailableImagePath(): string {
     return this._unavailableImagePath ?? defaultTemplatePath;
   }
 
   /**
-   * Sets the unavailableImagePath and re-compiles the SVG template if necessary.
+   * Sets the unavailableImagePath.
    */
   set unavailableImagePath(newValue: string | undefined) {
     this._unavailableImagePath = stringOrUndefined(newValue);
   }
 
   /**
-   * Returns the showTitle setting, or true if undefined.
+   * Gets the showTitle setting.
+   * @returns {boolean} True if showTitle is enabled. Defaults to true.
    */
-  get showTitle() {
+  get showTitle(): boolean {
     return this.settings.showTitle ?? true;
   }
 
   /**
-   * Returns the showLetter setting, or true if undefined.
+   * Gets the showLetter setting.
+   * @returns {boolean} True if showLetter is enabled. Defaults to true.
    */
-  get showLetter() {
+  get showLetter(): boolean {
     return this.settings.showLetter ?? true;
   }
 
   /**
    * Gets the settings.
+   * @returns {AtisLetterSettings} The settings.
    */
-  get settings() {
+  get settings(): AtisLetterSettings {
     if (this._settings === null) {
       throw new Error("Settings not initialized. This should never happen.");
     }
@@ -161,8 +168,7 @@ export class AtisLetterController extends BaseController {
   }
 
   /**
-   * Sets the settings. Also updates the private icon paths and
-   * compiled SVGs.
+   * Sets the settings. Also updates the private icon paths.
    */
   set settings(newValue: AtisLetterSettings) {
     this._settings = newValue;
@@ -176,8 +182,9 @@ export class AtisLetterController extends BaseController {
 
   /**
    * Gets the isUpdated state on the action.
+   * @returns {boolean} True if the ATIS is updated.
    */
-  public get isUpdated() {
+  public get isUpdated(): boolean {
     return this._isUpdated;
   }
 
@@ -204,13 +211,14 @@ export class AtisLetterController extends BaseController {
 
   /**
    * Gets the current ATIS letter.
+   * @returns {string | undefined} The current ATIS letter, or undefined if no letter is set.
    */
   get letter(): string | undefined {
     return this._letter;
   }
 
   /**
-   * Sets the current AITS letter.
+   * Sets the current ATIS letter and updates the display.
    */
   set letter(newLetter: string | undefined) {
     // This crazy check catches two situations where the state should not show as updated:
@@ -227,15 +235,16 @@ export class AtisLetterController extends BaseController {
   }
 
   /**
-   * Convenience method to return the action's title from settings.
+   * Gets the title value from settings.
+   * @returns { string | undefined } The title. Defaults to undefined.
    */
-  get title() {
+  get title(): string | undefined {
     return this.settings.title;
   }
   //#endregion
 
   /**
-   * Sets the image based on the state of the action.
+   * Sets the displayed image based on the state of the action.
    */
   private refreshImage() {
     const replacements = {
@@ -267,7 +276,7 @@ export class AtisLetterController extends BaseController {
   }
 
   /**
-   * Sets the title on the action.
+   * Sets the displayed title based on the state of the action.
    */
   private refreshTitle() {
     const title = new TitleBuilder();

src/controllers/baseController.ts

@@ -20,7 +20,7 @@ export abstract class BaseController implements Controller {
 
   /**
    * Initializes the BaseController.
-   * @param action The Stream Deck icon this wraps
+   * @param action The Stream Deck action this wraps
    */
   constructor(action: KeyAction | DialAction) {
     this.action = action;
@@ -48,11 +48,11 @@ export abstract class BaseController implements Controller {
   }
 
   /**
-   * Sets the image on the tracked action. If the image is a stored
+   * Sets the image on a key action. If the image is a stored
    * SVG template then the template is populated and used. Otherwise
    * the path is used directly.
-   * @param imagePath The path to the image
-   * @param replacements The replacements to use
+   * @param imagePath The path to the image.
+   * @param replacements The replacements to use.
    */
   setImage(imagePath: string, replacements: object) {
     const generatedSvg = svgManager.renderSvg(imagePath, replacements);
@@ -67,6 +67,13 @@ export abstract class BaseController implements Controller {
     }
   }
 
+  /**
+   * Sets the feedback image on a dial action. If the image is a stored
+   * SVG template then the template is populated and used. Otherwise
+   * the path is used directly.
+   * @param imagePath The path to the image.
+   * @param replacements The replacements to use.
+   */
   setFeedbackImage(imagePath: string, replacements: object) {
     if (!this.action.isDial()) {
       return;