From 186deb43d5dd7ffbf2ec02707c2b6c12b76c883c Mon Sep 17 00:00:00 2001
From: Amr Bashir <48618675+amrbashir@users.noreply.github.com>
Date: Tue, 13 Apr 2021 03:44:50 +0200
Subject: [PATCH] refactor: more consistent js-api docs (#1463)

---
 tooling/api/src/app.ts            |  32 ++++----
 tooling/api/src/cli.ts            |   6 +-
 tooling/api/src/dialog.ts         |  20 ++---
 tooling/api/src/event.ts          |  82 ++++++++++++++++++-
 tooling/api/src/fs.ts             | 123 +++++++++++++----------------
 tooling/api/src/globalShortcut.ts |  32 +++++---
 tooling/api/src/helpers/event.ts  |  89 ++-------------------
 tooling/api/src/http.ts           |  60 +++++++-------
 tooling/api/src/notification.ts   |  16 ++++
 tooling/api/src/path.ts           | 126 +++++++++++++++---------------
 tooling/api/src/shell.ts          |  25 +++---
 tooling/api/src/tauri.ts          |   8 +-
 tooling/api/src/updater.ts        |   2 +-
 tooling/api/src/window.ts         |  99 +++++++++++++++--------
 14 files changed, 378 insertions(+), 342 deletions(-)

diff --git a/tooling/api/src/app.ts b/tooling/api/src/app.ts
index eb17cd75d..b19af37d5 100644
--- a/tooling/api/src/app.ts
+++ b/tooling/api/src/app.ts
@@ -5,9 +5,9 @@
 import { invokeTauriCommand } from './helpers/tauri'
 
 /**
- * @name getVersion
- * @description Get application version
- * @returns {Promise<string>} Promise resolving to application version
+ * Gets the application version.
+ *
+ * @returns A promise resolving to application version.
  */
 async function getVersion(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -20,9 +20,9 @@ async function getVersion(): Promise<string> {
 }
 
 /**
- * @name getName
- * @description Get application name
- * @returns {Promise<string>} Promise resolving to application name
+ * Gets the application name.
+ *
+ * @returns A promise resolving to application name.
  */
 async function getName(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -35,9 +35,9 @@ async function getName(): Promise<string> {
 }
 
 /**
- * @name getTauriVersion
- * @description Get tauri version
- * @returns {Promise<string>} Promise resolving to tauri version
+ * Gets the tauri version.
+ *
+ * @returns A promise resolving to tauri version.
  */
 async function getTauriVersion(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -50,10 +50,10 @@ async function getTauriVersion(): Promise<string> {
 }
 
 /**
- * @name exit
- * @description Exits immediately with exitCode.
- * @param [exitCode] defaults to 0.
- * @returns {Promise<void>} Application is closing, nothing is returned
+ * Exits immediately with the given `exitCode`.
+ *
+ * @param exitCode The exit code to use
+ * @returns
  */
 async function exit(exitCode: number = 0): Promise<void> {
   return invokeTauriCommand({
@@ -67,9 +67,9 @@ async function exit(exitCode: number = 0): Promise<void> {
 }
 
 /**
- * @name relaunch
- * @description Relaunches the app when current instance exits.
- * @returns {Promise<void>} Application is restarting, nothing is returned
+ * Exits the current instance of the app then relaunches it.
+ *
+ * @returns
  */
 async function relaunch(): Promise<void> {
   return invokeTauriCommand({
diff --git a/tooling/api/src/cli.ts b/tooling/api/src/cli.ts
index 21dbc1286..e4538b943 100644
--- a/tooling/api/src/cli.ts
+++ b/tooling/api/src/cli.ts
@@ -12,7 +12,7 @@ export interface ArgMatch {
    */
   value: string | boolean | string[] | null
   /**
-   * number of occurrences
+   * Number of occurrences
    */
   occurrences: number
 }
@@ -28,7 +28,9 @@ export interface CliMatches {
 }
 
 /**
- * gets the CLI matches
+ * Gets the CLI matches.
+ *
+ * @returns A promise resolving to cli matches.
  */
 async function getMatches(): Promise<CliMatches> {
   return invokeTauriCommand<CliMatches>({
diff --git a/tooling/api/src/dialog.ts b/tooling/api/src/dialog.ts
index 65e298594..b029f6426 100644
--- a/tooling/api/src/dialog.ts
+++ b/tooling/api/src/dialog.ts
@@ -22,14 +22,9 @@ export interface SaveDialogOptions {
 }
 
 /**
- * @name openDialog
- * @description Open a file/directory selection dialog
- * @param {Object} [options]
- * @param {string} [options.filter]
- * @param {string} [options.defaultPath]
- * @param {boolean} [options.multiple=false]
- * @param {boolean} [options.directory=false]
- * @returns {Promise<string | string[]>} Promise resolving to the select path(s)
+ * Open a file/directory selection dialog
+ *
+ * @returns A promise resolving to the selected path(s)
  */
 async function open(
   options: OpenDialogOptions = {}
@@ -49,12 +44,9 @@ async function open(
 }
 
 /**
- * @name save
- * @description Open a file/directory save dialog
- * @param {Object} [options]
- * @param {string} [options.filter]
- * @param {string} [options.defaultPath]
- * @returns {Promise<string>} Promise resolving to the select path
+ * Open a file/directory save dialog.
+ *
+ * @returns A promise resolving to the selected path.
  */
 async function save(options: SaveDialogOptions = {}): Promise<string> {
   if (typeof options === 'object') {
diff --git a/tooling/api/src/event.ts b/tooling/api/src/event.ts
index bcf3c4a21..c5080baec 100644
--- a/tooling/api/src/event.ts
+++ b/tooling/api/src/event.ts
@@ -2,11 +2,89 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+import { invokeTauriCommand } from './helpers/tauri'
 import { emit as emitEvent } from './helpers/event'
+import { transformCallback } from './tauri'
 
+export interface Event<T> {
+  /** Event name */
+  event: string
+  /** Event identifier used to unlisten */
+  id: number
+  /** Event payload */
+  payload: T
+}
+
+export type EventCallback<T> = (event: Event<T>) => void
+
+export type UnlistenFn = () => void
+
+/**
+ * Unregister the event listener associated with the given id.
+ *
+ * @ignore
+ * @param eventId Event identifier
+ * @returns
+ */
+async function _unlisten(eventId: number): Promise<void> {
+  return invokeTauriCommand({
+    __tauriModule: 'Event',
+    message: {
+      cmd: 'unlisten',
+      eventId
+    }
+  })
+}
+
+/**
+ * Listen to an event from the backend.
+ *
+ * @param event Event name
+ * @param handler Event handler callback
+ * @return A promise resolving to a function to unlisten to the event.
+ */
+async function listen<T>(
+  event: string,
+  handler: EventCallback<T>
+): Promise<UnlistenFn> {
+  return invokeTauriCommand<number>({
+    __tauriModule: 'Event',
+    message: {
+      cmd: 'listen',
+      event,
+      handler: transformCallback(handler)
+    }
+  }).then((eventId) => {
+    return async () => _unlisten(eventId)
+  })
+}
+
+/**
+ * Listen to an one-off event from the backend.
+ *
+ * @param event Event name
+ * @param handler Event handler callback
+ * @returns A promise resolving to a function to unlisten to the event.
+ */
+async function once<T>(
+  event: string,
+  handler: EventCallback<T>
+): Promise<UnlistenFn> {
+  return listen<T>(event, (eventData) => {
+    handler(eventData)
+    _unlisten(eventData.id).catch(() => {})
+  })
+}
+
+/**
+ * Emits an event to the backend.
+ *
+ * @param event Event name
+ * @param [payload] Event payload
+ * @returns
+ */
 async function emit(event: string, payload?: string): Promise<void> {
   return emitEvent(event, undefined, payload)
 }
 
-export { listen, once } from './helpers/event'
-export { emit }
+export { listen, once, emit }
diff --git a/tooling/api/src/fs.ts b/tooling/api/src/fs.ts
index 98f8043f0..968042227 100644
--- a/tooling/api/src/fs.ts
+++ b/tooling/api/src/fs.ts
@@ -47,20 +47,21 @@ export interface FsBinaryFileOption {
 
 export interface FileEntry {
   path: string
-  // name of the directory/file
-  // can be null if the path terminates with `..`
+  /**
+   * Name of the directory/file
+   * can be null if the path terminates with `..`
+   */
   name?: string
-  // children of this entry if it's a directory; null otherwise
+  /** Children of this entry if it's a directory; null otherwise */
   children?: FileEntry[]
 }
 
 /**
- * @name readTextFile
- * @description Reads a file as text
- * @param {string} filePath path to the file
- * @param {FsOptions} [options] configuration object
- * @param {BaseDirectory} [options.dir] base directory
- * @return {Promise<string>}
+ * Reads a file as text.
+ *
+ * @param filePath Path to the file
+ * @param [options]
+ * @returns A promise resolving to a string of the file content.
  */
 async function readTextFile(
   filePath: string,
@@ -77,12 +78,11 @@ async function readTextFile(
 }
 
 /**
- * @name readBinaryFile
- * @description Reads a file as binary
- * @param {string} filePath path to the file
- * @param {FsOptions} [options] configuration object
- * @param {BaseDirectory} [options.dir] base directory
- * @return {Promise<number[]>}
+ * Reads a file as binary.
+ *
+ * @param filePath Path to the file
+ * @param [options]
+ * @returns A promise resolving to an array of the file bytes.
  */
 async function readBinaryFile(
   filePath: string,
@@ -99,14 +99,11 @@ async function readBinaryFile(
 }
 
 /**
- * writes a text file
+ * Writes a text file.
  *
- * @param file
- * @param file.path path of the file
- * @param file.contents contents of the file
- * @param [options] configuration object
- * @param [options.dir] base directory
- * @return
+ * @param file File configuration object
+ * @param [options]
+ * @returns
  */
 async function writeFile(
   file: FsTextFileOption,
@@ -133,10 +130,10 @@ async function writeFile(
 const CHUNK_SIZE = 65536
 
 /**
- * convert an Uint8Array to ascii string
+ * Convert an Uint8Array to ascii string.
  *
  * @param arr
- * @return ASCII string
+ * @returns An ASCII string.
  */
 function uint8ArrayToString(arr: Uint8Array): string {
   if (arr.length < CHUNK_SIZE) {
@@ -153,10 +150,10 @@ function uint8ArrayToString(arr: Uint8Array): string {
 }
 
 /**
- * convert an ArrayBuffer to base64 encoded string
+ * Convert an ArrayBuffer to base64 encoded string.
  *
  * @param buffer
- * @return base64 encoded string
+ * @returns A base64 encoded string.
  */
 function arrayBufferToBase64(buffer: ArrayBuffer): string {
   const str = uint8ArrayToString(new Uint8Array(buffer))
@@ -164,14 +161,11 @@ function arrayBufferToBase64(buffer: ArrayBuffer): string {
 }
 
 /**
- * writes a binary file
+ * Writes a binary file
  *
- * @param file
- * @param file.path path of the file
- * @param file.contents contents of the file
- * @param [options] configuration object
- * @param [options.dir] base directory
- * @return
+ * @param file File configuration object
+ * @param [options]
+ * @returns
  */
 async function writeBinaryFile(
   file: FsBinaryFileOption,
@@ -196,13 +190,11 @@ async function writeBinaryFile(
 }
 
 /**
- * list directory files
+ * List directory files.
  *
- * @param dir path to the directory to read
- * @param [options] configuration object
- * @param [options.recursive] whether to list dirs recursively or not
- * @param [options.dir] base directory
- * @return
+ * @param dir Path to the directory to read
+ * @param [options] Configuration object
+ * @returns
  */
 async function readDir(
   dir: string,
@@ -219,15 +211,13 @@ async function readDir(
 }
 
 /**
- * Creates a directory
+ * Creates a directory.
  * If one of the path's parent components doesn't exist
- * and the `recursive` option isn't set to true, it will be rejected
+ * and the `recursive` option isn't set to true, it will be rejected.
  *
- * @param dir path to the directory to create
- * @param [options] configuration object
- * @param [options.recursive] whether to create the directory's parent components or not
- * @param [options.dir] base directory
- * @return
+ * @param dir Path to the directory to create
+ * @param [options] Configuration object
+ * @returns
  */
 async function createDir(
   dir: string,
@@ -244,14 +234,12 @@ async function createDir(
 }
 
 /**
- * Removes a directory
- * If the directory is not empty and the `recursive` option isn't set to true, it will be rejected
+ * Removes a directory.
+ * If the directory is not empty and the `recursive` option isn't set to true, it will be rejected.
  *
- * @param dir path to the directory to remove
- * @param [options] configuration object
- * @param [options.recursive] whether to remove all of the directory's content or not
- * @param [options.dir] base directory
- * @return
+ * @param dir Path to the directory to remove
+ * @param [options] Configuration object
+ * @returns
  */
 async function removeDir(
   dir: string,
@@ -268,13 +256,12 @@ async function removeDir(
 }
 
 /**
- * Copy file
+ * Copys a file to a destination.
  *
- * @param source
- * @param destination
- * @param [options] configuration object
- * @param [options.dir] base directory
- * @return
+ * @param source A path of the file to copy
+ * @param destination A path for the destination file
+ * @param [options] Configuration object
+ * @returns
  */
 async function copyFile(
   source: string,
@@ -293,12 +280,11 @@ async function copyFile(
 }
 
 /**
- * Removes a file
+ * Removes a file.
  *
- * @param file path to the file to remove
- * @param [options] configuration object
- * @param [options.dir] base directory
- * @return
+ * @param file Path to the file to remove
+ * @param [options] Configuration object
+ * @returns
  */
 async function removeFile(
   file: string,
@@ -317,11 +303,10 @@ async function removeFile(
 /**
  * Renames a file
  *
- * @param oldPath
- * @param newPath
- * @param [options] configuration object
- * @param [options.dir] base directory
- * @return
+ * @param oldPath A path of the file to rename
+ * @param newPath A path of the new file name
+ * @param [options] Configuration object
+ * @returns
  */
 async function renameFile(
   oldPath: string,
diff --git a/tooling/api/src/globalShortcut.ts b/tooling/api/src/globalShortcut.ts
index 33f8a09bc..4f4a9b7cb 100644
--- a/tooling/api/src/globalShortcut.ts
+++ b/tooling/api/src/globalShortcut.ts
@@ -5,14 +5,18 @@
 import { invokeTauriCommand } from './helpers/tauri'
 import { transformCallback } from './tauri'
 
+export type ShortcutHandler = (shortcut: string) => void
+
 /**
- * Register a global shortcut
- * @param shortcut shortcut definition, modifiers and key separated by "+" e.g. CmdOrControl+Q
- * @param handler shortcut handler callback - takes the triggered shortcut as argument
+ * Register a global shortcut.
+ *
+ * @param shortcut Shortcut definition, modifiers and key separated by "+" e.g. CmdOrControl+Q
+ * @param handler Shortcut handler callback - takes the triggered shortcut as argument
+ * @returns
  */
 async function register(
   shortcut: string,
-  handler: (shortcut: string) => void
+  handler: ShortcutHandler
 ): Promise<void> {
   return invokeTauriCommand({
     __tauriModule: 'GlobalShortcut',
@@ -25,13 +29,15 @@ async function register(
 }
 
 /**
- * Register a collection of global shortcuts
- * @param shortcuts array of shortcut definitions, modifiers and key separated by "+" e.g. CmdOrControl+Q
- * @param handler shortcut handler callback - takes the triggered shortcut as argument
+ * Register a collection of global shortcuts.
+ *
+ * @param shortcuts Array of shortcut definitions, modifiers and key separated by "+" e.g. CmdOrControl+Q
+ * @param handler Shortcut handler callback - takes the triggered shortcut as argument
+ * @returns
  */
 async function registerAll(
   shortcuts: string[],
-  handler: (shortcut: string) => void
+  handler: ShortcutHandler
 ): Promise<void> {
   return invokeTauriCommand({
     __tauriModule: 'GlobalShortcut',
@@ -46,8 +52,8 @@ async function registerAll(
 /**
  * Determines whether the given shortcut is registered by this application or not.
  *
- * @param shortcuts array of shortcut definitions, modifiers and key separated by "+" e.g. CmdOrControl+Q
- * @return {Promise<boolean>} promise resolving to the state
+ * @param shortcut Array of shortcut definitions, modifiers and key separated by "+" e.g. CmdOrControl+Q
+ * @returns A promise resolving to the state.
  */
 async function isRegistered(shortcut: string): Promise<boolean> {
   return invokeTauriCommand({
@@ -60,8 +66,10 @@ async function isRegistered(shortcut: string): Promise<boolean> {
 }
 
 /**
- * Unregister a global shortcut
+ * Unregister a global shortcut.
+ *
  * @param shortcut shortcut definition, modifiers and key separated by "+" e.g. CmdOrControl+Q
+ * @returns
  */
 async function unregister(shortcut: string): Promise<void> {
   return invokeTauriCommand({
@@ -75,6 +83,8 @@ async function unregister(shortcut: string): Promise<void> {
 
 /**
  * Unregisters all shortcuts registered by the application.
+ *
+ * @returns
  */
 async function unregisterAll(): Promise<void> {
   return invokeTauriCommand({
diff --git a/tooling/api/src/helpers/event.ts b/tooling/api/src/helpers/event.ts
index c5fa31196..af1c73d60 100644
--- a/tooling/api/src/helpers/event.ts
+++ b/tooling/api/src/helpers/event.ts
@@ -1,89 +1,12 @@
-// Copyright 2019-2021 Tauri Programme within The Commons Conservancy
-// SPDX-License-Identifier: Apache-2.0
-// SPDX-License-Identifier: MIT
-
 import { invokeTauriCommand } from './tauri'
-import { transformCallback } from '../tauri'
-
-export interface Event<T> {
-  /// event name.
-  event: string
-  /// event identifier used to unlisten.
-  id: number
-  /// event payload.
-  payload: T
-}
-
-export type EventCallback<T> = (event: Event<T>) => void
-
-export type UnlistenFn = () => void
-
-async function _listen<T>(
-  event: string,
-  handler: EventCallback<T>
-): Promise<UnlistenFn> {
-  return invokeTauriCommand<number>({
-    __tauriModule: 'Event',
-    message: {
-      cmd: 'listen',
-      event,
-      handler: transformCallback(handler)
-    }
-  }).then((eventId) => {
-    return async () => _unlisten(eventId)
-  })
-}
 
 /**
- * Unregister the event listener associated with the given id.
+ * Emits an event to the backend.
  *
- * @param {number} eventId the event identifier
- */
-async function _unlisten(eventId: number): Promise<void> {
-  return invokeTauriCommand({
-    __tauriModule: 'Event',
-    message: {
-      cmd: 'unlisten',
-      eventId
-    }
-  })
-}
-
-/**
- * listen to an event from the backend
- *
- * @param event the event name
- * @param handler the event handler callback
- * @return {Promise<UnlistenFn>} a promise resolving to a function to unlisten to the event.
- */
-async function listen<T>(
-  event: string,
-  handler: EventCallback<T>
-): Promise<UnlistenFn> {
-  return _listen(event, handler)
-}
-
-/**
- * listen to an one-off event from the backend
- *
- * @param event the event name
- * @param handler the event handler callback
- */
-async function once<T>(
-  event: string,
-  handler: EventCallback<T>
-): Promise<UnlistenFn> {
-  return _listen<T>(event, (eventData) => {
-    handler(eventData)
-    _unlisten(eventData.id).catch(() => {})
-  })
-}
-
-/**
- * emits an event to the backend
- *
- * @param event the event name
- * @param [payload] the event payload
+ * @param event Event name
+ * @param [windowLabel] The label of the window to which the event is sent, if null/undefined the event will be sent to all windows
+ * @param [payload] Event payload
+ * @returns
  */
 async function emit(
   event: string,
@@ -101,4 +24,4 @@ async function emit(
   })
 }
 
-export { listen, once, emit }
+export { emit }
diff --git a/tooling/api/src/http.ts b/tooling/api/src/http.ts
index ead7f662a..1a600bb2b 100644
--- a/tooling/api/src/http.ts
+++ b/tooling/api/src/http.ts
@@ -81,7 +81,9 @@ export class Client {
   }
 
   /**
-   * drops the client instance
+   * Drops the client instance.
+   *
+   * @returns
    */
   async drop(): Promise<void> {
     return invokeTauriCommand({
@@ -94,11 +96,10 @@ export class Client {
   }
 
   /**
-   * makes a HTTP request
+   * Makes a HTTP request.
    *
-   * @param options request options
-   *
-   * @return promise resolving to the response
+   * @param options Request options
+   * @returns A promise resolving to the response.
    */
   async request<T>(options: HttpOptions): Promise<Response<T>> {
     return invokeTauriCommand({
@@ -112,12 +113,11 @@ export class Client {
   }
 
   /**
-   * makes a GET request
+   * Makes a GET request.
    *
-   * @param url request URL
-   * @param options request options
-   *
-   * @return promise resolving to the response
+   * @param url Request URL
+   * @param [options] Request options
+   * @returns A promise resolving to the response.
    */
   async get<T>(url: string, options?: RequestOptions): Promise<Response<T>> {
     return this.request({
@@ -128,13 +128,12 @@ export class Client {
   }
 
   /**
-   * makes a POST request
+   * Makes a POST request.
    *
-   * @param url request URL
-   * @param body request body
-   * @param options request options
-   *
-   * @return promise resolving to the response
+   * @param url Request URL
+   * @param [body] Request body
+   * @param [options] Request options
+   * @returns A promise resolving to the response.
    */
   async post<T>(
     url: string,
@@ -150,13 +149,12 @@ export class Client {
   }
 
   /**
-   * makes a PUT request
+   * Makes a PUT request.
    *
-   * @param url request URL
-   * @param body request body
-   * @param options request options
-   *
-   * @return promise resolving to the response
+   * @param url Request URL
+   * @param [body] Request body
+   * @param [options] Request options
+   * @returns A promise resolving to the response.
    */
   async put<T>(
     url: string,
@@ -172,12 +170,11 @@ export class Client {
   }
 
   /**
-   * makes a PATCH request
+   * Makes a PATCH request.
    *
-   * @param url request URL
-   * @param options request options
-   *
-   * @return promise resolving to the response
+   * @param url Request URL
+   * @param options Request options
+   * @returns A promise resolving to the response.
    */
   async patch<T>(url: string, options?: RequestOptions): Promise<Response<T>> {
     return this.request({
@@ -188,12 +185,11 @@ export class Client {
   }
 
   /**
-   * makes a DELETE request
+   * Makes a DELETE request.
    *
-   * @param url request URL
-   * @param options request options
-   *
-   * @return promise resolving to the response
+   * @param  url Request URL
+   * @param  options Request options
+   * @returns A promise resolving to the response.
    */
   async delete<T>(url: string, options?: RequestOptions): Promise<Response<T>> {
     return this.request({
diff --git a/tooling/api/src/notification.ts b/tooling/api/src/notification.ts
index d3b3d0adf..76afed471 100644
--- a/tooling/api/src/notification.ts
+++ b/tooling/api/src/notification.ts
@@ -13,6 +13,11 @@ export interface Options {
 export type PartialOptions = Omit<Options, 'title'>
 export type Permission = 'granted' | 'denied' | 'default'
 
+/**
+ * Checks if the permission to send notifications is granted.
+ *
+ * @returns
+ */
 async function isPermissionGranted(): Promise<boolean | null> {
   if (window.Notification.permission !== 'default') {
     return Promise.resolve(window.Notification.permission === 'granted')
@@ -25,10 +30,21 @@ async function isPermissionGranted(): Promise<boolean | null> {
   })
 }
 
+/**
+ * Requests the permission to send notifications.
+ *
+ * @returns A promise resolving to whether the user granted the permission or not.
+ */
 async function requestPermission(): Promise<Permission> {
   return window.Notification.requestPermission()
 }
 
+/**
+ * Sends a notification to the user.
+ *
+ * @param options Notification options
+ * @returns
+ */
 function sendNotification(options: Options | string): void {
   if (typeof options === 'string') {
     // eslint-disable-next-line no-new
diff --git a/tooling/api/src/path.ts b/tooling/api/src/path.ts
index 26e8f4ff3..513f89b59 100644
--- a/tooling/api/src/path.ts
+++ b/tooling/api/src/path.ts
@@ -6,9 +6,9 @@ import { invokeTauriCommand } from './helpers/tauri'
 import { BaseDirectory } from './fs'
 
 /**
- * @name appDir
- * @description Returns the path to the suggested directory for your app config files.
- * @return {Promise<string>}
+ * Returns the path to the suggested directory for your app config files.
+ *
+ * @returns
  */
 async function appDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -22,9 +22,9 @@ async function appDir(): Promise<string> {
 }
 
 /**
- * @name audioDir
- * @description Returns the path to the user's audio directory.
- * @return {Promise<string>}
+ * Returns the path to the user's audio directory.
+ *
+ * @returns
  */
 async function audioDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -38,9 +38,9 @@ async function audioDir(): Promise<string> {
 }
 
 /**
- * @name cacheDir
- * @description Returns the path to the user's cache directory.
- * @return {Promise<string>}
+ * Returns the path to the user's cache directory.
+ *
+ * @returns
  */
 async function cacheDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -54,9 +54,9 @@ async function cacheDir(): Promise<string> {
 }
 
 /**
- * @name configDir
- * @description Returns the path to the user's config directory.
- * @return {Promise<string>}
+ * Returns the path to the user's config directory.
+ *
+ * @returns
  */
 async function configDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -70,9 +70,9 @@ async function configDir(): Promise<string> {
 }
 
 /**
- * @name dataDir
- * @description Returns the path to the user's data directory.
- * @return {Promise<string>}
+ * Returns the path to the user's data directory.
+ *
+ * @returns
  */
 async function dataDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -86,9 +86,9 @@ async function dataDir(): Promise<string> {
 }
 
 /**
- * @name desktopDir
- * @description Returns the path to the user's desktop directory.
- * @return {Promise<string>}
+ * Returns the path to the user's desktop directory.
+
+ * @returns
  */
 async function desktopDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -102,9 +102,9 @@ async function desktopDir(): Promise<string> {
 }
 
 /**
- * @name documentDir
- * @description Returns the path to the user's document directory.
- * @return {Promise<string>}
+ * Returns the path to the user's document directory.
+ *
+ * @returns
  */
 async function documentDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -118,9 +118,9 @@ async function documentDir(): Promise<string> {
 }
 
 /**
- * @name downloadDir
- * @description Returns the path to the user's download directory.
- * @return {Promise<string>}
+ * Returns the path to the user's download directory.
+ *
+ * @returns
  */
 async function downloadDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -134,9 +134,9 @@ async function downloadDir(): Promise<string> {
 }
 
 /**
- * @name executableDir
- * @description Returns the path to the user's executable directory.
- * @return {Promise<string>}
+ * Returns the path to the user's executable directory.
+ *
+ * @returns
  */
 async function executableDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -150,9 +150,9 @@ async function executableDir(): Promise<string> {
 }
 
 /**
- * @name fontDir
- * @description Returns the path to the user's font directory.
- * @return {Promise<string>}
+ * Returns the path to the user's font directory.
+ *
+ * @returns
  */
 async function fontDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -166,9 +166,9 @@ async function fontDir(): Promise<string> {
 }
 
 /**
- * @name homeDir
- * @description Returns the path to the user's home directory.
- * @return {Promise<string>}
+ * Returns the path to the user's home directory.
+ *
+ * @returns
  */
 async function homeDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -182,9 +182,9 @@ async function homeDir(): Promise<string> {
 }
 
 /**
- * @name localDataDir
- * @description Returns the path to the user's local data directory.
- * @return {Promise<string>}
+ * Returns the path to the user's local data directory.
+ *
+ * @returns
  */
 async function localDataDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -198,9 +198,9 @@ async function localDataDir(): Promise<string> {
 }
 
 /**
- * @name pictureDir
- * @description Returns the path to the user's picture directory.
- * @return {Promise<string>}
+ * Returns the path to the user's picture directory.
+ *
+ * @returns
  */
 async function pictureDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -214,9 +214,9 @@ async function pictureDir(): Promise<string> {
 }
 
 /**
- * @name publicDir
- * @description Returns the path to the user's public directory.
- * @return {Promise<string>}
+ * Returns the path to the user's public directory.
+ *
+ * @returns
  */
 async function publicDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -230,9 +230,9 @@ async function publicDir(): Promise<string> {
 }
 
 /**
- * @name resourceDir
- * @description Returns the path to the user's resource directory.
- * @return {Promise<string>}
+ * Returns the path to the user's resource directory.
+ *
+ * @returns
  */
 async function resourceDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -246,9 +246,9 @@ async function resourceDir(): Promise<string> {
 }
 
 /**
- * @name runtimeDir
- * @descriptionReturns Returns the path to the user's runtime directory.
- * @return {Promise<string>}
+ * Returns the path to the user's runtime directory.
+ *
+ * @returns
  */
 async function runtimeDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -262,9 +262,9 @@ async function runtimeDir(): Promise<string> {
 }
 
 /**
- * @name templateDir
- * @descriptionReturns Returns the path to the user's template directory.
- * @return {Promise<string>}
+ * Returns the path to the user's template directory.
+ *
+ * @returns
  */
 async function templateDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -278,9 +278,9 @@ async function templateDir(): Promise<string> {
 }
 
 /**
- * @name videoDir
- * @descriptionReturns Returns the path to the user's video dir.
- * @return {Promise<string>}
+ * Returns the path to the user's video directory.
+ *
+ * @returns
  */
 async function videoDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -294,9 +294,9 @@ async function videoDir(): Promise<string> {
 }
 
 /**
- * @name currentDir
- * @descriptionReturns Returns the path to the current working dir.
- * @return {Promise<string>}
+ * Returns the path to the current working directory.
+ *
+ * @returns
  */
 async function currentDir(): Promise<string> {
   return invokeTauriCommand<string>({
@@ -310,11 +310,13 @@ async function currentDir(): Promise<string> {
 }
 
 /**
- * @name resolvePath
- * @descriptionReturns Resolves the path with the optional base directory.
- * @return {Promise<string>}
+ * Resolves the path with the optional base directory.
+ *
+ * @param path A path to resolve
+ * @param directory A base directory to use when resolving the given path
+ * @returns A path resolved to the given base directory.
  */
-async function resolvePath(
+async function resolve(
   path: string,
   directory: BaseDirectory
 ): Promise<string> {
@@ -348,5 +350,5 @@ export {
   templateDir,
   videoDir,
   currentDir,
-  resolvePath
+  resolve as resolvePath
 }
diff --git a/tooling/api/src/shell.ts b/tooling/api/src/shell.ts
index e0c0e9eca..a36b3c7be 100644
--- a/tooling/api/src/shell.ts
+++ b/tooling/api/src/shell.ts
@@ -6,12 +6,13 @@ import { invokeTauriCommand } from './helpers/tauri'
 import { transformCallback } from './tauri'
 
 /**
- * spawns a process
+ * Spawns a process.
  *
- * @param program the name of the program to execute e.g. 'mkdir' or 'node'
- * @param sidecar whether the program is a sidecar or a system program
- * @param [args] command args
- * @return promise resolving to the stdout text
+ * @param program The name of the program to execute e.g. 'mkdir' or 'node'
+ * @param sidecar Whether the program is a sidecar or a system program
+ * @param onEvent
+ * @param [args] Command args
+ * @returns A promise resolving to the process id.
  */
 async function execute(
   program: string,
@@ -118,11 +119,10 @@ class Command extends EventEmitter<'close' | 'error'> {
   }
 
   /**
-   * Creates a command to execute the given sidecar binary
+   * Creates a command to execute the given sidecar binary.
    *
-   * @param {string} program  Binary name
-   *
-   * @return {Command}
+   * @param program Binary name
+   * @returns
    */
   static sidecar(program: string, args: string | string[] = []): Command {
     const instance = new Command(program, args)
@@ -195,11 +195,12 @@ type CommandEvent =
   | Event<'Error', string>
 
 /**
- * opens a path or URL with the system's default app,
- * or the one specified with `openWith`
+ * Opens a path or URL with the system's default app,
+ * or the one specified with `openWith`.
  *
  * @param path the path or URL to open
- * @param openWith the app to open the file or URL with
+ * @param [openWith] the app to open the file or URL with
+ * @returns
  */
 async function open(path: string, openWith?: string): Promise<void> {
   return invokeTauriCommand({
diff --git a/tooling/api/src/tauri.ts b/tooling/api/src/tauri.ts
index 29f9fd626..47668cdfa 100644
--- a/tooling/api/src/tauri.ts
+++ b/tooling/api/src/tauri.ts
@@ -46,11 +46,11 @@ export interface InvokeArgs {
 }
 
 /**
- * sends a message to the backend
+ * Sends a message to the backend.
  *
- * @param args
- *
- * @return {Promise<T>} Promise resolving or rejecting to the backend response
+ * @param cmd
+ * @param [args]
+ * @return A promise resolving or rejecting to the backend response.
  */
 async function invoke<T>(cmd: string, args: InvokeArgs = {}): Promise<T> {
   return new Promise((resolve, reject) => {
diff --git a/tooling/api/src/updater.ts b/tooling/api/src/updater.ts
index b686be32f..f30280bd2 100644
--- a/tooling/api/src/updater.ts
+++ b/tooling/api/src/updater.ts
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
-import { once, listen, emit, UnlistenFn } from './helpers/event'
+import { once, listen, emit, UnlistenFn } from './event'
 
 export type UpdateStatus = 'PENDING' | 'ERROR' | 'DONE' | 'UPTODATE'
 
diff --git a/tooling/api/src/window.ts b/tooling/api/src/window.ts
index 8b160376f..6bf66ba07 100644
--- a/tooling/api/src/window.ts
+++ b/tooling/api/src/window.ts
@@ -3,7 +3,8 @@
 // SPDX-License-Identifier: MIT
 
 import { invokeTauriCommand } from './helpers/tauri'
-import { EventCallback, UnlistenFn, emit, listen, once } from './helpers/event'
+import { EventCallback, UnlistenFn, listen, once } from './event'
+import { emit } from './helpers/event'
 
 interface WindowDef {
   label: string
@@ -40,11 +41,11 @@ class WebviewWindowHandle {
   }
 
   /**
-   * Listen to an event emitted by the webview
+   * Listen to an event emitted by the webview.
    *
-   * @param event the event name
-   * @param handler the event handler callback
-   * @return {Promise<UnlistenFn>} a promise resolving to a function to unlisten to the event.
+   * @param event Event name
+   * @param handler Event handler callback
+   * @returns A promise resolving to a function to unlisten to the event.
    */
   async listen<T>(
     event: string,
@@ -61,10 +62,11 @@ class WebviewWindowHandle {
   }
 
   /**
-   * Listen to an one-off event emitted by the webview
+   * Listen to an one-off event emitted by the webview.
    *
-   * @param event the event name
-   * @param handler the event handler callback
+   * @param event Event name
+   * @param handler Event handler callback
+   * @returns A promise resolving to a function to unlisten to the event.
    */
   async once<T>(event: string, handler: EventCallback<T>): Promise<UnlistenFn> {
     if (this._handleTauriEvent(event, handler)) {
@@ -78,10 +80,10 @@ class WebviewWindowHandle {
   }
 
   /**
-   * emits an event to the webview
+   * Emits an event to the webview.
    *
-   * @param event the event name
-   * @param [payload] the event payload
+   * @param event Event name
+   * @param [payload] Event payload
    */
   async emit(event: string, payload?: string): Promise<void> {
     if (localTauriEvents.includes(event)) {
@@ -129,9 +131,8 @@ class WebviewWindow extends WebviewWindowHandle {
   /**
    * Gets the WebviewWindow handle for the webview associated with the given label.
    *
-   * @param {string} label the webview window label.
-   *
-   * @return {WebviewWindowHandle} the handle to communicate with the webview or null if the webview doesn't exist
+   * @param label The webview window label.
+   * @returns The handle to communicate with the webview or null if the webview doesn't exist.
    */
   static getByLabel(label: string): WebviewWindowHandle | null {
     if (getAll().some((w) => w.label === label)) {
@@ -141,9 +142,12 @@ class WebviewWindow extends WebviewWindowHandle {
   }
 }
 
-class WindowManager {
+export class WindowManager {
   /**
    * Updates the window resizable flag.
+   *
+   * @param resizable
+   * @returns
    */
   async setResizable(resizable: boolean): Promise<void> {
     return invokeTauriCommand({
@@ -156,9 +160,10 @@ class WindowManager {
   }
 
   /**
-   * sets the window title
+   * Sets the window title.
    *
-   * @param title the new title
+   * @param title The new title
+   * @returns
    */
   async setTitle(title: string): Promise<void> {
     return invokeTauriCommand({
@@ -172,6 +177,8 @@ class WindowManager {
 
   /**
    * Maximizes the window.
+   *
+   * @returns
    */
   async maximize(): Promise<void> {
     return invokeTauriCommand({
@@ -184,6 +191,8 @@ class WindowManager {
 
   /**
    * Unmaximizes the window.
+   *
+   * @returns
    */
   async unmaximize(): Promise<void> {
     return invokeTauriCommand({
@@ -196,6 +205,8 @@ class WindowManager {
 
   /**
    * Minimizes the window.
+   *
+   * @returns
    */
   async minimize(): Promise<void> {
     return invokeTauriCommand({
@@ -208,6 +219,8 @@ class WindowManager {
 
   /**
    * Unminimizes the window.
+   *
+   * @returns
    */
   async unminimize(): Promise<void> {
     return invokeTauriCommand({
@@ -220,6 +233,8 @@ class WindowManager {
 
   /**
    * Sets the window visibility to true.
+   *
+   * @returns
    */
   async show(): Promise<void> {
     return invokeTauriCommand({
@@ -232,6 +247,8 @@ class WindowManager {
 
   /**
    * Sets the window visibility to false.
+   *
+   * @returns
    */
   async hide(): Promise<void> {
     return invokeTauriCommand({
@@ -244,6 +261,8 @@ class WindowManager {
 
   /**
    * Closes the window.
+   *
+   * @returns
    */
   async close(): Promise<void> {
     return invokeTauriCommand({
@@ -257,7 +276,8 @@ class WindowManager {
   /**
    * Whether the window should have borders and bars.
    *
-   * @param {boolean} decorations whether the window should have borders and bars
+   * @param decorations Whether the window should have borders and bars
+   * @returns
    */
   async setDecorations(decorations: boolean): Promise<void> {
     return invokeTauriCommand({
@@ -272,7 +292,8 @@ class WindowManager {
   /**
    * Whether the window should always be on top of other windows.
    *
-   * @param {boolean} alwaysOnTop whether the window should always be on top of other windows or not
+   * @param alwaysOnTop Whether the window should always be on top of other windows or not
+   * @returns
    */
   async setAlwaysOnTop(alwaysOnTop: boolean): Promise<void> {
     return invokeTauriCommand({
@@ -287,7 +308,8 @@ class WindowManager {
   /**
    * Sets the window width.
    *
-   * @param {number} width the new window width
+   * @param width The new window width
+   * @returns
    */
   async setWidth(width: number): Promise<void> {
     return invokeTauriCommand({
@@ -302,7 +324,8 @@ class WindowManager {
   /**
    * Sets the window height.
    *
-   * @param {number} height the new window height
+   * @param height The new window height
+   * @returns
    */
   async setHeight(height: number): Promise<void> {
     return invokeTauriCommand({
@@ -317,8 +340,9 @@ class WindowManager {
   /**
    * Resizes the window.
    *
-   * @param {number} width the new window width
-   * @param {number} height the new window height
+   * @param width The new window width
+   * @param height The new window height
+   * @returns
    */
   async resize(width: number, height: number): Promise<void> {
     return invokeTauriCommand({
@@ -334,8 +358,9 @@ class WindowManager {
   /**
    * Sets the window min size.
    *
-   * @param {number} minWidth the new window min width
-   * @param {number} minHeight the new window min height
+   * @param minWidth The new window min width
+   * @param minHeight The new window min height
+   * @returns
    */
   async setMinSize(minWidth: number, minHeight: number): Promise<void> {
     return invokeTauriCommand({
@@ -351,8 +376,9 @@ class WindowManager {
   /**
    * Sets the window max size.
    *
-   * @param {number} maxWidth the new window max width
-   * @param {number} maxHeight the new window max height
+   * @param maxWidth The new window max width
+   * @param maxHeight The new window max height
+   * @returns
    */
   async setMaxSize(maxWidth: number, maxHeight: number): Promise<void> {
     return invokeTauriCommand({
@@ -368,7 +394,8 @@ class WindowManager {
   /**
    * Sets the window x position.
    *
-   * @param {number} x the new window x position
+   * @param x The new window x position
+   * @returns
    */
   async setX(x: number): Promise<void> {
     return invokeTauriCommand({
@@ -383,7 +410,8 @@ class WindowManager {
   /**
    * Sets the window y position.
    *
-   * @param {number} y the new window y position
+   * @param y The new window y position
+   * @returns
    */
   async setY(y: number): Promise<void> {
     return invokeTauriCommand({
@@ -398,8 +426,9 @@ class WindowManager {
   /**
    * Sets the window position.
    *
-   * @param {number} x the new window x position
-   * @param {number} y the new window y position
+   * @param x The new window x position
+   * @param y The new window y position
+   * @returns
    */
   async setPosition(x: number, y: number): Promise<void> {
     return invokeTauriCommand({
@@ -415,7 +444,8 @@ class WindowManager {
   /**
    * Sets the window fullscreen state.
    *
-   * @param {boolean} fullscreen whether the window should go to fullscreen or not
+   * @param fullscreen Whether the window should go to fullscreen or not
+   * @returns
    */
   async setFullscreen(fullscreen: boolean): Promise<void> {
     return invokeTauriCommand({
@@ -428,9 +458,10 @@ class WindowManager {
   }
 
   /**
-   * Sets the window icon
+   * Sets the window icon.
    *
-   * @param {string | number[]} icon icon bytes or path to the icon file
+   * @param icon Icon bytes or path to the icon file
+   * @returns
    */
   async setIcon(icon: 'string' | number[]): Promise<void> {
     return invokeTauriCommand({