Add docs for everything non-boilerplate

Show missing documentation warnings when running the 'doc' npm script.
Add doc comments for everything non-boilerplate. I'm still not sure if
documenting the boilerplate would be meaningful.
Ignore src/node_modules when generating documentation. This folder
exists because webpack insisted ssh2 be installed in release/app because
it's a native dependency, which causes npm install to create a modules
folder in src. Go figure.

.eslintignore

@@ -31,3 +31,5 @@ npm-debug.log.*
 # eslint ignores hidden directories by default:
 # https://github.com/eslint/eslint/issues/8429
 !.erb
+
+docs

package.json

@@ -39,7 +39,7 @@
     "build:dll": "cross-env NODE_ENV=development TS_NODE_TRANSPILE_ONLY=true webpack --config ./.erb/configs/webpack.config.renderer.dev.dll.ts",
     "build:main": "cross-env NODE_ENV=production TS_NODE_TRANSPILE_ONLY=true webpack --config ./.erb/configs/webpack.config.main.prod.ts",
     "build:renderer": "cross-env NODE_ENV=production TS_NODE_TRANSPILE_ONLY=true webpack --config ./.erb/configs/webpack.config.renderer.prod.ts",
-    "doc": "typedoc --name Dawn src/**/*.ts src/**/*.tsx",
+    "doc": "typedoc --name Dawn --excludePrivate false --exclude src/node_modules/** --exclude src/__tests__/** src/**/*.ts src/**/*.tsx --validation",
     "postinstall": "ts-node .erb/scripts/check-native-dep.js && electron-builder install-app-deps && npm run build:dll",
     "lint": "cross-env NODE_ENV=development eslint . --ext .js,.jsx,.ts,.tsx",
     "package": "ts-node ./.erb/scripts/clean.js dist && npm run build && electron-builder build --publish never && npm run build:dll",

src/common/IpcEventTypes.ts

@@ -19,41 +19,76 @@ export type MainChannels = 'main-file-control' | 'main-quit';
  * 'ready-to-show'.
  */
 export interface RendererInitData {
+  /**
+   * User-presentable Dawn version string.
+   */
   dawnVersion: string;
+  /**
+   * The IP address used to communicate with the robot's runtime, retrieved from persistent config.
+   */
   robotIPAddress: string;
+  /**
+   * The IP address used to upload code to the robot, retrieved from persistent config.
+   */
   robotSSHAddress: string;
+  /**
+   * The IP address of the field controller, retrieved from persistent config.
+   */
   fieldIPAddress: string;
+  /**
+   * The field station number to connect to, retrieved from persistent config.
+   */
   fieldStationNumber: string;
+  /**
+   * Whether the user should be warned when uploading code with unsaved changes in the editor (since
+   * these won't be uploaded), retrieved from persistent config.
+   */
   showDirtyUploadWarning: boolean;
 }
 /**
  * Data for a specialization of the renderer-file-control event, sent when the main process wants to
  * try saving the code and needs to ask the renderer process for the content of the editor.
  */
-interface RendererFcPrmtSaveData {
+export interface RendererFileControlPromptSaveData {
+  /**
+   * The subtype of file control event.
+   */
   type: 'promptSave';
+  /**
+   * Whether the user should be prompted to choose a save path even if one is remembered from the
+   * last save or load.
+   */
   forceDialog: boolean;
 }
 /**
  * Data for a specialization of the renderer-file-control event, sent when the main process wants to
  * try loading a file into the editor and needs to ask the renderer process if this is ok (if there
  * are no unsaved changes).
  */
-interface RendererFcPrmtLoadData {
+export interface RendererFileControlPromptLoadData {
+  /**
+   * The subtype of file control event.
+   */
   type: 'promptLoad';
 }
 /**
  * Data for a specialization of the renderer-file-control event, sent when the main process has
  * successfully saved the code and the renderer should clear the dirty editor indicator.
  */
-interface RendererFcSaveData {
+export interface RendererFileControlSaveData {
+  /**
+   * The subtype of file control event.
+   */
   type: 'didSave';
 }
 /**
  * Data for a specialization of the renderer-file-control event, sent when the main process has
  * successfully loaded code and the renderer should store the retrieved content in the editor.
  */
-interface RendererFcOpenData {
+export interface RendererFileControlOpenData {
+  /**
+   * The subtype of file control event.
+   */
   type: 'didOpen';
   /**
    * The loaded code.
@@ -69,32 +104,47 @@ interface RendererFcOpenData {
  * Data for a specialization of the renderer-file-control event, sent when the main process has
  * successfully saved or loaded code and the renderer should update the path shown in the editor.
  */
-interface RendererFcPathData {
+export interface RendererFileControlPathData {
+  /**
+   * The subtype of file control event.
+   */
   type: 'didChangePath';
+  /**
+   * The new save path to display in the editor.
+   */
   path: string;
 }
 /**
  * Data for a specialization of the renderer-file-control event, sent when the main process detects
  * external changes to the currently open file and the renderer should set the dirty editor
  * indicator.
  */
-interface RendererFcExtChangeData {
+export interface RendererFileControlExtChangeData {
+  /**
+   * The subtype of file control event.
+   */
   type: 'didExternalChange';
 }
 /**
  * Data for a specialization of the renderer-file-control event, sent when the main process wants to
  * upload code from the last saved file to the robot and needs to ask the renderer process to notify
  * the user in case this would ignore unsaved changes in the editor.
  */
-interface RendererFcPrmtUploadData {
+export interface RendererFileControlPromptUploadData {
+  /**
+   * The subtype of file control event.
+   */
   type: 'promptUpload';
 }
 /**
  * Data for a specialization of the renderer-file-control event, sent when the main process wants to
  * download code from the robot into the editor and needs to ask the renderer if this is ok (if
  * there are no unsaved changes).
  */
-interface RendererFcPrmtDownloadData {
+export interface RendererFileControlPromptDownloadData {
+  /**
+   * The subtype of file control event.
+   */
   type: 'promptDownload';
 }
 /**
@@ -109,15 +159,17 @@ interface RendererFileControlPromptCreateNewFile {
  * information related to the code file and editor.
  */
 export type RendererFileControlData =
-  | RendererFcPrmtSaveData
-  | RendererFcPrmtLoadData
-  | RendererFcSaveData
-  | RendererFcOpenData
-  | RendererFcPathData
-  | RendererFcExtChangeData
-  | RendererFcPrmtUploadData
-  | RendererFcPrmtDownloadData
-  | RendererFileControlPromptCreateNewFile;
+  | RendererFileControlPromptSaveData
+  | RendererFileControlPromptLoadData
+  | RendererFileControlSaveData
+  | RendererFileControlOpenData
+  | RendererFileControlPathData
+  | RendererFileControlExtChangeData
+  | RendererFileControlPromptUploadData
+  | RendererFileControlPromptDownloadData
+  | RendererFileControlPromptCreateNewFile
+  ;
+>>>>>>> 69c0059 (Add docs for everything non-boilerplate)
 /**
  * Data for the renderer-post-console event sent by the main process to add a console message to the
  * AppConsole.
@@ -128,41 +180,78 @@ export type RendererPostConsoleData = AppConsoleMessage;
  * changes.
  */
 export interface RendererRobotUpdateData {
+  /**
+   * User-presentable runtime version string. May be omitted if the value has not changed since the
+   * last update.
+   */
   runtimeVersion?: string;
+  /**
+   * Robot battery voltage in volts. May be omitted if the value has not changed since the last
+   * update.
+   */
   robotBatteryVoltage?: number;
+  /**
+   * Robot connection latency in milliseconds. May be omitted if the value has not changed since the
+   * last update.
+   */
   robotLatencyMs?: number;
 }
 
 /**
  * Data for a specialization of the main-file-control event, sent by the renderer to
  * initiate/respond to a request to save the code.
  */
-interface MainFcSaveData {
+export interface MainFileControlSaveData {
+  /**
+   * The subtype of file control event.
+   */
   type: 'save';
+  /**
+   * Whether the user should be prompted to choose a save path even if one is remembered from the
+   * last save or load.
+   */
   forceDialog: boolean;
+  /**
+   * The content to save to the file.
+   */
   content: string;
 }
 /**
  * Data for a specialization of the main-file-control event, sent by the renderer to
  * initiate/authorize a request to load code into the editor.
  */
-interface MainFcLoadData {
+export interface MainFileControlLoadData {
+  /**
+   * The subtype of file control event.
+   */
   type: 'load';
 }
 /**
  * Data for a specialization of the main-file-control event, sent by the renderer to
  * initiate/respond to a request to upload the last opened file to the robot.
  */
-interface MainFcUploadData {
+export interface MainFileControlUploadData {
+  /**
+   * The subtype of file control event.
+   */
   type: 'upload';
+  /**
+   * The IP address to connect to via SSH when uploading code.
+   */
   robotSSHAddress: string;
 }
 /**
  * Data for a specialization of the main-file-control event, sent by the renderer to
  * initiate/respond to a request to download the code on the robot into the editor.
  */
-interface MainFcDownloadData {
+export interface MainFileControlDownloadData {
+  /**
+   * The subtype of file control event.
+   */
   type: 'download';
+  /**
+   * The IP address to connect to via SSH when uploading code.
+   */
   robotSSHAddress: string;
 }
 /**
@@ -178,19 +267,42 @@ export interface MainFileControlClearSavePathData {
  * to the code file and editor.
  */
 export type MainFileControlData =
+<<<<<<< HEAD
   | MainFcSaveData
   | MainFcLoadData
   | MainFcUploadData
   | MainFcDownloadData
   | MainFileControlClearSavePathData;
+=======
+  | MainFileControlSaveData
+  | MainFileControlLoadData
+  | MainFileControlUploadData
+  | MainFileControlDownloadData;
+>>>>>>> 69c0059 (Add docs for everything non-boilerplate)
 /**
  * Data for the main-quit event sent by the renderer both to authorize a request to quit and to send
  * updated configuration data that should be saved before the program closes.
  */
 export interface MainQuitData {
+  /**
+   * The IP address used to communicate with the robot's runtime, to be saved to persistent config.
+   */
   robotIPAddress: string;
+  /**
+   * The IP address used to upload code to the robot, to be saved to persistent config.
+   */
   robotSSHAddress: string;
+  /**
+   * The IP address of the field controller, to be saved to persistent config.
+   */
   fieldIPAddress: string;
+  /**
+   * The field station number to connect to, to be saved to persistent config.
+   */
   fieldStationNumber: string;
+  /**
+   * Whether the user should be warned when uploading code with unsaved changes in the editor (since
+   * these won't be uploaded), to be saved to persistent config.
+   */
   showDirtyUploadWarning: boolean;
 }

src/main/Config.ts

@@ -2,10 +2,26 @@
  * Describes persistent configuration for Dawn.
  */
 export default interface Config {
+  /**
+   * The IP address used to communicate with the robot's runtime.
+   */
   robotIPAddress: string;
+  /**
+   * The IP address used to upload code to the robot.
+   */
   robotSSHAddress: string;
+  /**
+   * The IP address of the field controller.
+   */
   fieldIPAddress: string;
+  /**
+   * The field station number to connect to.
+   */
   fieldStationNumber: string;
+  /**
+   * Whether the user should be warned when uploading code with unsaved changes in the editor (since
+   * these won't be uploaded).
+   */
   showDirtyUploadWarning: boolean;
 }
 
@@ -55,5 +71,7 @@ export function coerceToConfig(template: unknown): Config {
   ) {
     config.showDirtyUploadWarning = true;
   }
-  return config as Config; // By now we're sure all the fields (and maybe some more) are set
+  // By now we're sure all the required fields are set (and really typescript should be too, so I
+  // don't really understand why a cast is needed here)
+  return config as Config;
 }

src/main/MainApp.ts

@@ -106,12 +106,12 @@ export default class MainApp {
    * Persistent configuration loaded when MainApp is constructed and saved when the main window is
    * closed.
    */
-  #config: Config;
+  readonly #config: Config;
 
   /**
    * CodeTransfer used to upload/download code to/from the robot.
    */
-  #codeTransfer: CodeTransfer;
+  readonly #codeTransfer: CodeTransfer;
 
   /**
    * @param mainWindow - the BrowserWindow.
@@ -460,20 +460,44 @@ export default class MainApp {
     );
   }
 
+  /**
+   * Typed wrapper function for sending an event to the main window.
+   * @param channel - the channel to send the event on
+   */
   #sendToRenderer(channel: 'renderer-quit-request'): void;
 
+  /**
+   * Typed wrapper function for sending an event to the main window.
+   * @param channel - the channel to send the event on
+   * @param data - a payload for the renderer-init event
+   */
   #sendToRenderer(channel: 'renderer-init', data: RendererInitData): void;
 
+  /**
+   * Typed wrapper function for sending an event to the main window.
+   * @param channel - the channel to send the event on
+   * @param data - a payload for the renderer-file-control event
+   */
   #sendToRenderer(
     channel: 'renderer-file-control',
     data: RendererFileControlData,
   ): void;
 
+  /**
+   * Typed wrapper function for sending an event to the main window.
+   * @param channel - the channel to send the event on
+   * @param data - a payload for the renderer-post-console event
+   */
   #sendToRenderer(
     channel: 'renderer-post-console',
     data: RendererPostConsoleData,
   ): void;
 
+  /**
+   * Typed wrapper function for sending an event to the main window.
+   * @param channel - the channel to send the event on
+   * @param data - a payload for the renderer-robot-update event
+   */
   #sendToRenderer(
     channel: 'renderer-robot-update',
     data: RendererRobotUpdateData,