chore: convert JSDoc comments to TSDoc

.eslintrc.js

@@ -25,7 +25,7 @@ const config = {
     'plugin:import/recommended', // Used along with eslint-plugin-import to sort imports with recommended standards
     'plugin:import/typescript', // To handle import order cases for typescript files
   ],
-  plugins: ['import'],
+  plugins: ['import', 'eslint-plugin-tsdoc'],
   rules: {
     // Place to specify ESLint rules. Can be used to overwrite rules specified from the extended configs
     // e.g. "@typescript-eslint/explicit-function-return-type": "off",
@@ -76,7 +76,16 @@ const config = {
         pathGroupsExcludedImportTypes: ['react'],
       },
     ],
+    'tsdoc/syntax': 'error',
   },
+  overrides: [
+    {
+      files: ['rtl-spec/**', 'tests/**'],
+      rules: {
+        'tsdoc/syntax': 'off',
+      },
+    },
+  ],
   // the static folder is linted by standard
   ignorePatterns: ['/out', '/.webpack', '/coverage', '/static'],
 };

package.json

@@ -120,6 +120,7 @@
     "eslint-plugin-import": "^2.27.5",
     "eslint-plugin-prettier": "^5.0.0",
     "eslint-plugin-react": "^7.32.2",
+    "eslint-plugin-tsdoc": "^0.3.0",
     "fork-ts-checker-webpack-plugin": "^8.0.0",
     "husky": "^9.0.11",
     "jest": "^29.6.2",

src/main/about-panel.ts

@@ -8,8 +8,6 @@ import contributorsJSON from '../../static/contributors.json';
 
 /**
  * Sets Fiddle's About panel options on Linux and macOS
- *
- * @returns
  */
 export function setupAboutPanel(): void {
   const contributors: Array<string> = [];

src/main/content.ts

@@ -23,8 +23,8 @@ const TEST_TEMPLATE_BRANCH = 'test-template';
  * Ensure we have a fiddle for the specified Electron branch.
  * If we don't have it already, download it from electron-quick-start.
  *
- * @param {string} branch - Electron branchname, e.g. `12-x-y` or `main`
- * @returns {Promise<string>} Path to the folder where the fiddle is kept
+ * @param branch - Electron branchname, e.g. `12-x-y` or `main`
+ * @returns Path to the folder where the fiddle is kept
  */
 async function prepareTemplate(branch: string): Promise<string> {
   let folder = path.join(TEMPLATES_DIR, `electron-quick-start-${branch}`);
@@ -69,8 +69,7 @@ const templateCache: Record<string, Promise<EditorValues>> = {};
 /**
  * Get a cached copy of the Electron branch's fiddle.
  *
- * @param {string} branch - Electron branchname, e.g. `12-x-y` or `main`
- * @returns {Promise<EditorValues>}
+ * @param branch - Electron branchname, e.g. `12-x-y` or `main`
  */
 function getQuickStart(branch: string): Promise<EditorValues> {
   // Load the template for that branch.
@@ -86,8 +85,6 @@ function getQuickStart(branch: string): Promise<EditorValues> {
 
 /**
  * Get a cached copy of the Electron Test fiddle.
- *
- * @returns {Promise<EditorValues>}
  */
 export function getTestTemplate(): Promise<EditorValues> {
   return getQuickStart(TEST_TEMPLATE_BRANCH);
@@ -96,8 +93,7 @@ export function getTestTemplate(): Promise<EditorValues> {
 /**
  * Get a cached copy of the fiddle for the specified Electron version.
  *
- * @param {string} version - Electron version, e.g. 12.0.0
- * @returns {Promise<EditorValues>}
+ * @param version - Electron version, e.g. 12.0.0
  */
 export function getTemplate(version: string): Promise<EditorValues> {
   const major = Number.parseInt(version);

src/main/context-menu.ts

@@ -11,8 +11,6 @@ import { IpcEvents } from '../ipc-events';
 
 /**
  * Returns items related to running the current fiddle.
- *
- * @returns {Array<MenuItemConstructorOptions>}
  */
 export function getRunItems(): Array<MenuItemConstructorOptions> {
   return [
@@ -36,9 +34,6 @@ export function getRunItems(): Array<MenuItemConstructorOptions> {
  * Possibly returns items interacting with the Monaco editor.
  * Our check for "are we in the Monaco editor" is pretty crude -
  * we just assume that we are if we can paste text.
- *
- * @param {ContextMenuParams} { pageURL, editFlags }
- * @returns {Array<MenuItemConstructorOptions>}
  */
 export function getMonacoItems({
   pageURL,
@@ -105,10 +100,6 @@ export function getMonacoItems({
 
 /**
  * Possibly returns the `Inspect Element` item.
- *
- * @param {BrowserWindow} browserWindow
- * @param {ContextMenuParams} { x, y }
- * @returns {Array<MenuItemConstructorOptions>}
  */
 export function getInspectItems(
   browserWindow: BrowserWindow,
@@ -137,8 +128,6 @@ export function getInspectItems(
 
 /**
  * Creates a context menu for a given BrowserWindow
- *
- * @param {BrowserWindow} browserWindow
  */
 export function createContextMenu(browserWindow: BrowserWindow) {
   browserWindow.webContents.on('context-menu', (_event, props) => {

src/main/devtools.ts

@@ -2,9 +2,6 @@ import { isDevMode } from './utils/devmode';
 
 /**
  * Installs developer tools if we're in dev mode.
- *
- * @export
- * @returns {Promise<void>}
  */
 export async function setupDevTools(): Promise<void> {
   if (!isDevMode()) return;

src/main/dialogs.ts

@@ -11,9 +11,7 @@ import { IpcEvents } from '../ipc-events';
 /**
  * Build a default name for a local Electron version
  * from its dirname.
- *
- * @param {string} folderPath
- * @return {string} human-readable local build name
+ * @returns human-readable local build name
  */
 function makeLocalName(folderPath: string): string {
   // take a dirname like '/home/username/electron/gn/main/src/out/testing'
@@ -35,9 +33,6 @@ function makeLocalName(folderPath: string): string {
 
 /**
  * Verifies if the local electron path is valid
- *
- * @param {string} folderPath
- * @return {boolean}
  */
 function isValidElectronPath(folderPath: string): boolean {
   const execPath = Installer.getExecPath(folderPath);
@@ -46,8 +41,6 @@ function isValidElectronPath(folderPath: string): boolean {
 
 /**
  * Listens to IPC events related to dialogs and message boxes
- *
- * @export
  */
 export function setupDialogs() {
   ipcMainManager.on(IpcEvents.SHOW_WARNING_DIALOG, (event, args) => {
@@ -77,8 +70,6 @@ export function setupDialogs() {
 
 /**
  * Shows a warning dialog
- *
- * @param {Electron.MessageBoxOptions} args
  */
 function showWarningDialog(
   window: BrowserWindow,

src/main/files.ts

@@ -81,9 +81,6 @@ export async function showSaveDialog(
 
 /**
  * Confirm it's OK to save files in `folder`
- *
- * @param {string} filePath
- * @returns {Promise<boolean>}
  */
 async function isOkToSaveAt(filePath: string): Promise<boolean> {
   return (
@@ -96,9 +93,6 @@ async function isOkToSaveAt(filePath: string): Promise<boolean> {
 /**
  * Pops open a confirmation dialog, asking the user if they really
  * want to overwrite an existing file
- *
- * @param {string} filePath
- * @returns {Promise<boolean>}
  */
 async function confirmFileOverwrite(filePath: string): Promise<boolean> {
   try {

src/main/ipc.ts

@@ -13,9 +13,6 @@ import {
  * The main purpose of this class is to be the central
  * gathering place for IPC calls the main process sends
  * or listens to.
- *
- * @class IpcManager
- * @extends {EventEmitter}
  */
 class IpcMainManager extends EventEmitter {
   public readyWebContents = new WeakSet<Electron.WebContents>();
@@ -50,10 +47,6 @@ class IpcMainManager extends EventEmitter {
   /**
    * Send an IPC message to an instance of Electron.WebContents.
    * If none is specified, we'll automatically go with the main window.
-   *
-   * @param {IpcEvents} channel
-   * @param {Array<any>} [args]
-   * @param {Electron.WebContents} [target]
    */
   public send(
     channel: IpcEvents,

src/main/main.ts

@@ -77,8 +77,6 @@ export async function onReady() {
 
 /**
  * Handle the "before-quit" event
- *
- * @export
  */
 export function onBeforeQuit() {
   ipcMainManager.send(IpcEvents.BEFORE_QUIT);

src/main/menu.ts

@@ -25,9 +25,6 @@ import { SHOW_ME_TEMPLATES } from '../templates';
 
 /**
  * Is the passed object a constructor for an Electron Menu?
- *
- * @param {(Array<Electron.MenuItemConstructorOptions> | Electron.Menu)} [submenu]
- * @returns {submenu is Array<Electron.MenuItemConstructorOptions>}
  */
 function isSubmenu(
   submenu?: Array<MenuItemConstructorOptions> | Menu,
@@ -37,8 +34,6 @@ function isSubmenu(
 
 /**
  * Returns additional items for the help menu
- *
- * @returns {Array<Electron.MenuItemConstructorOptions>}
  */
 function getHelpItems(): Array<MenuItemConstructorOptions> {
   const items: MenuItemConstructorOptions[] = [];
@@ -112,8 +107,6 @@ function getHelpItems(): Array<MenuItemConstructorOptions> {
 /**
  * Depending on the OS, the `Preferences` either go into the `Fiddle`
  * menu (macOS) or under `File` (Linux, Windows)
- *
- * @returns {Array<Electron.MenuItemConstructorOptions>}
  */
 function getPreferencesItems(): Array<MenuItemConstructorOptions> {
   return [
@@ -135,8 +128,6 @@ function getPreferencesItems(): Array<MenuItemConstructorOptions> {
 
 /**
  * Returns the Exit items
- *
- * @returns {Array<Electron.MenuItemConstructorOptions>}
  */
 function getQuitItems(): Array<MenuItemConstructorOptions> {
   return [
@@ -151,8 +142,6 @@ function getQuitItems(): Array<MenuItemConstructorOptions> {
 
 /**
  * Returns the top-level "File" menu
- *
- * @returns {Array<Electron.MenuItemConstructorOptions>}
  */
 function getTasksMenu(): MenuItemConstructorOptions {
   const tasksMenu: Array<MenuItemConstructorOptions> = [
@@ -219,8 +208,6 @@ function getShowMeMenu(
 
 /**
  * Returns the top-level "File" menu
- *
- * @returns {Array<Electron.MenuItemConstructorOptions>}
  */
 function getFileMenu(
   acceleratorsToBlock: BlockableAccelerator[] = [],

src/main/npm.ts

@@ -49,10 +49,6 @@ export async function getIsPackageManagerInstalled(
 
 /**
  * Installs given modules to a given folder.
- *
- * @param {PMOperationOptions} { dir, packageManager }
- * @param {...Array<string>} names
- * @returns {Promise<string>}
  */
 export async function addModules(
   { dir, packageManager }: PMOperationOptions,
@@ -73,11 +69,7 @@ export async function addModules(
 }
 
 /**
- * Execute an "{packageManager} run" command
- *
- * @param {PMOperationOptions} { dir, packageManager }
- * @param {string} command
- * @returns {Promise<string>}
+ * Execute an "\{packageManager\} run" command
  */
 export async function packageRun(
   { dir, packageManager }: PMOperationOptions,

src/main/templates.ts

@@ -10,9 +10,6 @@ import { IpcEvents } from '../ipc-events';
 
 /**
  * Returns expected content for a given name.
- *
- * @param {string} name
- * @returns {Promise<EditorValues>}
  */
 export function getTemplateValues(name: string): Promise<EditorValues> {
   const templatePath = path.join(STATIC_DIR, 'show-me', name.toLowerCase());

src/main/themes.ts

@@ -19,10 +19,6 @@ export const THEMES_PATH = path.join(CONFIG_PATH, 'themes');
 
 /**
  * Read in a theme file.
- *
- * @export
- * @param {string} [name]
- * @returns {Promise<FiddleTheme | null>}
  */
 export async function readThemeFile(
   name?: string,
@@ -48,10 +44,6 @@ export async function readThemeFile(
 
 /**
  * Create theme file and show in folder.
- *
- * @param {FiddleTheme} theme
- * @param {string} [name]
- * @returns {Promise<LoadedFiddleTheme>}
  */
 export async function createThemeFile(
   theme: FiddleTheme | LoadedFiddleTheme,
@@ -87,8 +79,6 @@ export async function createThemeFile(
 
 /**
  * Reads and then returns all available themes.
- *
- * @returns {Promise<Array<LoadedFiddleTheme>>}
  */
 export async function getAvailableThemes(): Promise<Array<LoadedFiddleTheme>> {
   const themes: Array<LoadedFiddleTheme> = [defaultDark, defaultLight];

src/main/utils/check-first-run.ts

@@ -11,8 +11,6 @@ const getConfigPath = () => {
 /**
  * Whether or not the app is being run for
  * the first time
- *
- * @returns {boolean}
  */
 export function isFirstRun(): boolean {
   const configPath = getConfigPath();

src/main/utils/devmode.ts

@@ -1,7 +1,5 @@
 /**
  * Are we currently running in development mode?
- *
- * @returns {boolean}
  */
 export function isDevMode(): boolean {
   return !!process.defaultApp;

src/main/utils/exec.ts

@@ -6,8 +6,6 @@ import shellEnv from 'shell-env';
 /**
  * On macOS & Linux, we need to fix the $PATH environment variable
  * so that we can call `npm`.
- *
- * @returns {Promise<void>}
  */
 export const maybeFixPath = (() => {
   // Singleton: We don't want to do this more than once.
@@ -31,10 +29,6 @@ export const maybeFixPath = (() => {
 
 /**
  * Execute a command in a directory.
- *
- * @param {string} dir
- * @param {string} cliArgs
- * @returns {Promise<string>}
  */
 export async function exec(dir: string, cliArgs: string): Promise<string> {
   await maybeFixPath();

src/main/utils/get-project-name.ts

@@ -4,9 +4,6 @@ import * as namor from 'namor';
 
 /**
  * Returns a name for this project
- *
- * @param {string} [localPath]
- * @returns {string}
  */
 export function getProjectName(localPath?: string): string {
   if (localPath) {

src/main/utils/get-username.ts

@@ -2,9 +2,6 @@ import * as os from 'node:os';
 
 /**
  * Returns the current username
- *
- * @export
- * @returns {string}
  */
 export const getUsername = (() => {
   let username = '';