feat(api): documentation (#1694)

* feat(api): documentation

* more docs [skip ci]

tooling/api/src/app.ts

@@ -2,12 +2,17 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Get application metadata.
+ * @packageDocumentation
+ */
+
 import { invokeTauriCommand } from './helpers/tauri'
 
 /**
  * Gets the application version.
  *
- * @returns A promise resolving to application version.
+ * @returns A promise resolving to the application version.
  */
 async function getVersion(): Promise<string> {
   return invokeTauriCommand<string>({

tooling/api/src/bundle.ts

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/** @ignore */ /** */
+
 import 'regenerator-runtime/runtime'
 import * as app from './app'
 import * as cli from './cli'

tooling/api/src/cli.ts

@@ -2,6 +2,11 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Parse arguments from your Command Line Interface.
+ * @packageDocumentation
+ */
+
 import { invokeTauriCommand } from './helpers/tauri'
 
 export interface ArgMatch {
@@ -28,9 +33,9 @@ export interface CliMatches {
 }
 
 /**
- * Gets the CLI matches.
+ * Parse the arguments provided to the current process and get the matches using the configuration defined `tauri.conf.json > tauri > cli`.
  *
- * @returns A promise resolving to cli matches.
+ * @returns A promise resolving to the parsed arguments.
  */
 async function getMatches(): Promise<CliMatches> {
   return invokeTauriCommand<CliMatches>({

tooling/api/src/dialog.ts

@@ -2,23 +2,44 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Native system dialogs for opening and saving files.
+ * @packageDocumentation
+ */
+
 import { invokeTauriCommand } from './helpers/tauri'
 
+/** Extension filters for the file dialog. */
 export interface DialogFilter {
+  /** Filter name. */
   name: string
+  /**
+   * Extensions to filter, without a `.` prefix.
+   * @example
+   * ```typescript
+   * extensions: ['svg', 'png']
+   * ```
+   */
   extensions: string[]
 }
 
+/** Options for the open dialog. */
 export interface OpenDialogOptions {
+  /** The filters of the dialog. */
   filters?: DialogFilter[]
+  /** Initial directory or file path. It must exist. */
   defaultPath?: string
-  fileName?: string
+  /** Whether the dialog allows multiple selection or not. */
   multiple?: boolean
+  /** Whether the dialog is a directory selection or not. */
   directory?: boolean
 }
 
+/** Options for the save dialog. */
 export interface SaveDialogOptions {
+  /** The filters of the dialog. */
   filters?: DialogFilter[]
+  /** Initial directory or file path. It must exist. */
   defaultPath?: string
 }
 

tooling/api/src/event.ts

@@ -2,6 +2,11 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * The event system allows you to emit events to the backend and listen to events from it.
+ * @packageDocumentation
+ */
+
 import { invokeTauriCommand } from './helpers/tauri'
 import { emit as emitEvent } from './helpers/event'
 import { transformCallback } from './tauri'

tooling/api/src/fs.ts

@@ -2,6 +2,11 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Access the file system.
+ * @packageDocumentation
+ */
+
 import { invokeTauriCommand } from './helpers/tauri'
 
 export enum BaseDirectory {
@@ -57,11 +62,11 @@ export interface FileEntry {
 }
 
 /**
- * Reads a file as text.
+ * Reads a file as UTF-8 encoded string.
  *
- * @param filePath Path to the file
- * @param [options]
- * @returns A promise resolving to a string of the file content.
+ * @param filePath Path to the file.
+ * @param options Configuration object.
+ * @returns A promise resolving to the file content as a UTF-8 encoded string.
  */
 async function readTextFile(
   filePath: string,
@@ -78,11 +83,11 @@ async function readTextFile(
 }
 
 /**
- * Reads a file as binary.
+ * Reads a file as byte array.
  *
- * @param filePath Path to the file
- * @param [options]
- * @returns A promise resolving to an array of the file bytes.
+ * @param filePath Path to the file.
+ * @param options Configuration object.
+ * @returns A promise resolving to the file bytes array.
  */
 async function readBinaryFile(
   filePath: string,
@@ -101,9 +106,9 @@ async function readBinaryFile(
 /**
  * Writes a text file.
  *
- * @param file File configuration object
- * @param [options]
- * @returns
+ * @param file File configuration object.
+ * @param options Configuration object.
+ * @returns A promise indicating the success or failure of the operation.
  */
 async function writeFile(
   file: FsTextFileOption,
@@ -127,11 +132,13 @@ async function writeFile(
   })
 }
 
+/** @ignore */
 const CHUNK_SIZE = 65536
 
 /**
  * Convert an Uint8Array to ascii string.
  *
+ * @ignore
  * @param arr
  * @returns An ASCII string.
  */
@@ -152,6 +159,7 @@ function uint8ArrayToString(arr: Uint8Array): string {
 /**
  * Convert an ArrayBuffer to base64 encoded string.
  *
+ * @ignore
  * @param buffer
  * @returns A base64 encoded string.
  */
@@ -161,11 +169,11 @@ function arrayBufferToBase64(buffer: ArrayBuffer): string {
 }
 
 /**
- * Writes a binary file
+ * Writes a binary file.
  *
- * @param file File configuration object
- * @param [options]
- * @returns
+ * @param file Write configuration object.
+ * @param options Configuration object.
+ * @returns A promise indicating the success or failure of the operation.
  */
 async function writeBinaryFile(
   file: FsBinaryFileOption,
@@ -192,9 +200,9 @@ async function writeBinaryFile(
 /**
  * List directory files.
  *
- * @param dir Path to the directory to read
- * @param [options] Configuration object
- * @returns
+ * @param dir Path to the directory to read.
+ * @param options Configuration object.
+ * @returns A promise resolving to the directory entries.
  */
 async function readDir(
   dir: string,
@@ -213,11 +221,11 @@ async function readDir(
 /**
  * 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, the promise will be rejected.
  *
- * @param dir Path to the directory to create
- * @param [options] Configuration object
- * @returns
+ * @param dir Path to the directory to create.
+ * @param options Configuration object.
+ * @returns A promise indicating the success or failure of the operation.
  */
 async function createDir(
   dir: string,
@@ -235,11 +243,11 @@ 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.
+ * If the directory is not empty and the `recursive` option isn't set to true, the promise will be rejected.
  *
- * @param dir Path to the directory to remove
- * @param [options] Configuration object
- * @returns
+ * @param dir Path to the directory to remove.
+ * @param options Configuration object.
+ * @returns A promise indicating the success or failure of the operation.
  */
 async function removeDir(
   dir: string,
@@ -258,10 +266,10 @@ async function removeDir(
 /**
  * Copys a file to a destination.
  *
- * @param source A path of the file to copy
- * @param destination A path for the destination file
- * @param [options] Configuration object
- * @returns
+ * @param source A path of the file to copy.
+ * @param destination A path for the destination file.
+ * @param options Configuration object.
+ * @returns A promise indicating the success or failure of the operation.
  */
 async function copyFile(
   source: string,
@@ -282,9 +290,9 @@ async function copyFile(
 /**
  * Removes a file.
  *
- * @param file Path to the file to remove
- * @param [options] Configuration object
- * @returns
+ * @param file Path to the file to remove.
+ * @param options Configuration object.
+ * @returns A promise indicating the success or failure of the operation.
  */
 async function removeFile(
   file: string,
@@ -301,12 +309,12 @@ async function removeFile(
 }
 
 /**
- * Renames a file
+ * Renames a file.
  *
- * @param oldPath A path of the file to rename
- * @param newPath A path of the new file name
- * @param [options] Configuration object
- * @returns
+ * @param oldPath A path of the file to rename.
+ * @param newPath A path of the new file name.
+ * @param options Configuration object.
+ * @returns A promise indicating the success or failure of the operation.
  */
 async function renameFile(
   oldPath: string,

tooling/api/src/globalShortcut.ts

@@ -2,6 +2,11 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Register global shortcuts.
+ * @packageDocumentation
+ */
+
 import { invokeTauriCommand } from './helpers/tauri'
 import { transformCallback } from './tauri'
 

tooling/api/src/helpers/event.ts

@@ -1,3 +1,9 @@
+// Copyright 2019-2021 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+/** @ignore */ /** */
+
 import { invokeTauriCommand } from './tauri'
 
 /**

tooling/api/src/helpers/tauri.ts

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/** @ignore */ /** */
+
 import { invoke } from '../tauri'
 
 export type TauriModule =

tooling/api/src/http.ts

@@ -2,6 +2,11 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Access the HTTP client written in Rust.
+ * @packageDocumentation
+ */
+
 import { invokeTauriCommand } from './helpers/tauri'
 
 export interface ClientOptions {
@@ -17,32 +22,63 @@ export enum ResponseType {
 
 export type Part = 'string' | number[]
 
+/** The body object to be used on POST and PUT requests. */
 export class Body {
   type: string
   payload: unknown
 
+  /** @ignore */
   constructor(type: string, payload: unknown) {
     this.type = type
     this.payload = payload
   }
 
+  /**
+   * Creates a new form data body.
+   *
+   * @param data The body data.
+   *
+   * @return The body object ready to be used on the POST and PUT requests.
+   */
   static form(data: Record<string, Part>): Body {
     return new Body('Form', data)
   }
 
+  /**
+   * Creates a new JSON body.
+   *
+   * @param data The body JSON object.
+   *
+   * @return The body object ready to be used on the POST and PUT requests.
+   */
   static json(data: Record<any, any>): Body {
     return new Body('Json', data)
   }
 
+  /**
+   * Creates a new UTF-8 string body.
+   *
+   * @param data The body string.
+   *
+   * @return The body object ready to be used on the POST and PUT requests.
+   */
   static text(value: string): Body {
     return new Body('Text', value)
   }
 
+  /**
+   * Creates a new byte array body.
+   *
+   * @param data The body byte array.
+   *
+   * @return The body object ready to be used on the POST and PUT requests.
+   */
   static bytes(bytes: number[]): Body {
     return new Body('Bytes', bytes)
   }
 }
 
+/** The request HTTP verb. */
 export type HttpVerb =
   | 'GET'
   | 'POST'
@@ -54,6 +90,7 @@ export type HttpVerb =
   | 'CONNECT'
   | 'TRACE'
 
+/** Options object sent to the backend. */
 export interface HttpOptions {
   method: HttpVerb
   url: string
@@ -64,18 +101,26 @@ export interface HttpOptions {
   responseType?: ResponseType
 }
 
+/** Request options. */
 export type RequestOptions = Omit<HttpOptions, 'method' | 'url'>
+/** Options for the `fetch` API. */
 export type FetchOptions = Omit<HttpOptions, 'url'>
 
+/** Response object. */
 export interface Response<T> {
+  /** The request URL. */
   url: string
+  /** The response status code. */
   status: number
+  /** The response headers. */
   headers: Record<string, string>
+  /** The response data. */
   data: T
 }
 
 export class Client {
   id: number
+  /** @ignore */
   constructor(id: number) {
     this.id = id
   }
@@ -96,9 +141,9 @@ export class Client {
   }
 
   /**
-   * Makes a HTTP request.
+   * Makes an HTTP request.
    *
-   * @param options Request options
+   * @param options The request options.
    * @returns A promise resolving to the response.
    */
   async request<T>(options: HttpOptions): Promise<Response<T>> {
@@ -115,8 +160,8 @@ export class Client {
   /**
    * Makes a GET request.
    *
-   * @param url Request URL
-   * @param [options] Request options
+   * @param url The request URL.
+   * @param options The request options.
    * @returns A promise resolving to the response.
    */
   async get<T>(url: string, options?: RequestOptions): Promise<Response<T>> {
@@ -130,9 +175,9 @@ export class Client {
   /**
    * Makes a POST request.
    *
-   * @param url Request URL
-   * @param [body] Request body
-   * @param [options] Request options
+   * @param url The request URL.
+   * @param body The body of the request.
+   * @param options The request options.
    * @returns A promise resolving to the response.
    */
   async post<T>(
@@ -151,9 +196,9 @@ export class Client {
   /**
    * Makes a PUT request.
    *
-   * @param url Request URL
-   * @param [body] Request body
-   * @param [options] Request options
+   * @param url The request URL.
+   * @param body The body of the request.
+   * @param options Request options.
    * @returns A promise resolving to the response.
    */
   async put<T>(
@@ -172,8 +217,8 @@ export class Client {
   /**
    * Makes a PATCH request.
    *
-   * @param url Request URL
-   * @param options Request options
+   * @param url The request URL.
+   * @param options The request options.
    * @returns A promise resolving to the response.
    */
   async patch<T>(url: string, options?: RequestOptions): Promise<Response<T>> {
@@ -187,8 +232,8 @@ export class Client {
   /**
    * Makes a DELETE request.
    *
-   * @param  url Request URL
-   * @param  options Request options
+   * @param url The request URL.
+   * @param options The request options.
    * @returns A promise resolving to the response.
    */
   async delete<T>(url: string, options?: RequestOptions): Promise<Response<T>> {
@@ -200,6 +245,13 @@ export class Client {
   }
 }
 
+/**
+ * Creates a new client using the specified options.
+ *
+ * @param options Client configuration.
+ *
+ * @return A promise resolving to the client instance.
+ */
 async function getClient(options?: ClientOptions): Promise<Client> {
   return invokeTauriCommand<number>({
     __tauriModule: 'Http',
@@ -210,8 +262,16 @@ async function getClient(options?: ClientOptions): Promise<Client> {
   }).then((id) => new Client(id))
 }
 
+/** @ignore */
 let defaultClient: Client | null = null
 
+/**
+ * Perform an HTTP request using the default client.
+ *
+ * @param url The request URL.
+ * @param options The fetch options.
+ * @return The response object.
+ */
 async function fetch<T>(
   url: string,
   options?: FetchOptions

tooling/api/src/index.ts

@@ -1,4 +1,10 @@
 // Copyright 2019-2021 Tauri Programme within The Commons Conservancy
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
+
+/**
+ * The Tauri API allows you to interface with the backend layer.
+ * @packageDocumentation
+ */
+
 export * from './bundle'

tooling/api/src/notification.ts

@@ -2,15 +2,26 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Send notifications to your user. Can also be used with the Notification Web API.
+ * @packageDocumentation
+ */
+
 import { invokeTauriCommand } from './helpers/tauri'
 
+/**
+ * Options to send a notification.
+ */
 export interface Options {
+  /** Notification title. */
   title: string
+  /** Optional notification body. */
   body?: string
+  /** Optional notification icon. */
   icon?: string
 }
 
-export type PartialOptions = Omit<Options, 'title'>
+/** Possible permission values. */
 export type Permission = 'granted' | 'denied' | 'default'
 
 /**
@@ -42,8 +53,7 @@ async function requestPermission(): Promise<Permission> {
 /**
  * Sends a notification to the user.
  *
- * @param options Notification options
- * @returns
+ * @param options Notification options.
  */
 function sendNotification(options: Options | string): void {
   if (typeof options === 'string') {

tooling/api/src/path.ts

@@ -5,8 +5,14 @@
 import { invokeTauriCommand } from './helpers/tauri'
 import { BaseDirectory } from './fs'
 
+/**
+ * Read common system paths such as home, config and cache directories.
+ * @packageDocumentation
+ */
+
 /**
  * Returns the path to the suggested directory for your app config files.
+ * Resolves to `${configDir}/${bundleIdentifier}`, where `bundleIdentifier` is the value configured on `tauri.conf.json > tauri > bundle > identifier`.
  *
  * @returns
  */
@@ -23,6 +29,12 @@ async function appDir(): Promise<string> {
 
 /**
  * Returns the path to the user's audio directory.
+ * # Linux
+ * Resolves to `$XDG_MUSIC_DIR`.
+ * # macOS
+ * Resolves to `$HOME/Music`.
+ * # Windows
+ * Resolves to `{FOLDERID_Music}`.
  *
  * @returns
  */
@@ -39,6 +51,12 @@ async function audioDir(): Promise<string> {
 
 /**
  * Returns the path to the user's cache directory.
+ * # Linux
+ * Resolves to `$XDG_CACHE_HOME` or `$HOME/.cache`.
+ * # macOS
+ * Resolves to `$HOME/Library/Caches`.
+ * # Windows
+ * Resolves to `{FOLDERID_LocalAppData}`.
  *
  * @returns
  */
@@ -55,6 +73,12 @@ async function cacheDir(): Promise<string> {
 
 /**
  * Returns the path to the user's config directory.
+ * # Linux
+ * Resolves to `$XDG_CONFIG_HOME` or `$HOME/.config`.
+ * # macOS
+ * Resolves to `$HOME/Library/Application Support`.
+ * # Windows
+ * Resolves to `{FOLDERID_LocalAppData}`.
  *
  * @returns
  */
@@ -71,6 +95,12 @@ async function configDir(): Promise<string> {
 
 /**
  * Returns the path to the user's data directory.
+ * # Linux
+ * Resolves to `$XDG_DATA_HOME` or `$HOME/.local/share`.
+ * # macOS
+ * Resolves to `$HOME/Library/Application Support`.
+ * # Windows
+ * Resolves to `{FOLDERID_RoamingAppData}`.
  *
  * @returns
  */
@@ -87,6 +117,12 @@ async function dataDir(): Promise<string> {
 
 /**
  * Returns the path to the user's desktop directory.
+ * # Linux
+ * Resolves to `$XDG_DESKTOP_DIR`.
+ * # macOS
+ * Resolves to `$HOME/Library/Desktop`.
+ * # Windows
+ * Resolves to `{FOLDERID_Desktop}`.
 
  * @returns
  */
@@ -103,6 +139,12 @@ async function desktopDir(): Promise<string> {
 
 /**
  * Returns the path to the user's document directory.
+ * # Linux
+ * Resolves to `$XDG_DOCUMENTS_DIR`.
+ * # macOS
+ * Resolves to `$HOME/Documents`.
+ * # Windows
+ * Resolves to `{FOLDERID_Documents}`.
  *
  * @returns
  */
@@ -119,6 +161,12 @@ async function documentDir(): Promise<string> {
 
 /**
  * Returns the path to the user's download directory.
+ * # Linux
+ * Resolves to `$XDG_DOWNLOAD_DIR`.
+ * # macOS
+ * Resolves to `$HOME/Downloads`.
+ * # Windows
+ * Resolves to `{FOLDERID_Downloads}`.
  *
  * @returns
  */
@@ -135,6 +183,12 @@ async function downloadDir(): Promise<string> {
 
 /**
  * Returns the path to the user's executable directory.
+ * # Linux
+ * Resolves to `$XDG_BIN_HOME/../bin` or `$XDG_DATA_HOME/../bin` or `$HOME/.local/bin`.
+ * # macOS
+ * Not supported.
+ * # Windows
+ * Not supported.
  *
  * @returns
  */
@@ -151,6 +205,12 @@ async function executableDir(): Promise<string> {
 
 /**
  * Returns the path to the user's font directory.
+ * # Linux
+ * Resolves to `$XDG_DATA_HOME/fonts` or `$HOME/.local/share/fonts`.
+ * # macOS
+ * Resolves to `$HOME/Library/Fonts`.
+ * # Windows
+ * Not supported.
  *
  * @returns
  */
@@ -167,6 +227,12 @@ async function fontDir(): Promise<string> {
 
 /**
  * Returns the path to the user's home directory.
+ * # Linux
+ * Resolves to `$HOME`.
+ * # macOS
+ * Resolves to `$HOME`.
+ * # Windows
+ * Resolves to `{FOLDERID_Profile}`.
  *
  * @returns
  */
@@ -183,6 +249,12 @@ async function homeDir(): Promise<string> {
 
 /**
  * Returns the path to the user's local data directory.
+ * # Linux
+ * Resolves to `$XDG_DATA_HOME` or `$HOME/.local/share`.
+ * # macOS
+ * Resolves to `$HOME/Library/Application Support`.
+ * # Windows
+ * Resolves to `{FOLDERID_LocalAppData}`.
  *
  * @returns
  */
@@ -199,6 +271,12 @@ async function localDataDir(): Promise<string> {
 
 /**
  * Returns the path to the user's picture directory.
+ * # Linux
+ * Resolves to `$XDG_PICTURES_DIR`.
+ * # macOS
+ * Resolves to `$HOME/Pictures`.
+ * # Windows
+ * Resolves to `{FOLDERID_Pictures}`.
  *
  * @returns
  */
@@ -215,6 +293,12 @@ async function pictureDir(): Promise<string> {
 
 /**
  * Returns the path to the user's public directory.
+ * # Linux
+ * Resolves to `$XDG_PUBLICSHARE_DIR`.
+ * # macOS
+ * Resolves to `$HOME/Public`.
+ * # Windows
+ * Resolves to `{FOLDERID_Public}`.
  *
  * @returns
  */
@@ -247,6 +331,12 @@ async function resourceDir(): Promise<string> {
 
 /**
  * Returns the path to the user's runtime directory.
+ * # Linux
+ * Resolves to `$XDG_RUNTIME_DIR`.
+ * # macOS
+ * Not supported.
+ * # Windows
+ * Not supported.
  *
  * @returns
  */
@@ -263,6 +353,12 @@ async function runtimeDir(): Promise<string> {
 
 /**
  * Returns the path to the user's template directory.
+ * # Linux
+ * Resolves to `$XDG_TEMPLATES_DIR`.
+ * # macOS
+ * Not supported.
+ * # Windows
+ * Resolves to `{FOLDERID_Templates}`.
  *
  * @returns
  */
@@ -279,6 +375,12 @@ async function templateDir(): Promise<string> {
 
 /**
  * Returns the path to the user's video directory.
+ * # Linux
+ * Resolves to `$XDG_VIDEOS_DIR`.
+ * # macOS
+ * Resolves to `$HOME/Movies`.
+ * # Windows
+ * Resolves to `{FOLDERID_Videos}`.
  *
  * @returns
  */
@@ -316,7 +418,7 @@ async function currentDir(): Promise<string> {
  * @param directory A base directory to use when resolving the given path
  * @returns A path resolved to the given base directory.
  */
-async function resolve(
+async function resolvePath(
   path: string,
   directory: BaseDirectory
 ): Promise<string> {
@@ -350,5 +452,5 @@ export {
   templateDir,
   videoDir,
   currentDir,
-  resolve as resolvePath
+  resolvePath
 }

tooling/api/src/process.ts

@@ -4,11 +4,16 @@
 
 import { invokeTauriCommand } from './helpers/tauri'
 
+/**
+ * Perform operations on the current process.
+ * @packageDocumentation
+ */
+
 /**
  * Exits immediately with the given `exitCode`.
  *
- * @param exitCode The exit code to use
- * @returns
+ * @param exitCode The exit code to use.
+ * @returns A promise indicating the success or failure of the operation.
  */
 async function exit(exitCode: number = 0): Promise<void> {
   return invokeTauriCommand({
@@ -23,7 +28,7 @@ async function exit(exitCode: number = 0): Promise<void> {
 /**
  * Exits the current instance of the app then relaunches it.
  *
- * @returns
+ * @returns A promise indicating the success or failure of the operation.
  */
 async function relaunch(): Promise<void> {
   return invokeTauriCommand({

tooling/api/src/shell.ts

@@ -5,6 +5,12 @@
 import { invokeTauriCommand } from './helpers/tauri'
 import { transformCallback } from './tauri'
 
+/**
+ * Access the system shell.
+ * Allows you to spawn child processes and manage files and URLs using their default application.
+ * @packageDocumentation
+ */
+
 interface SpawnOptions {
   /** Current working directory. */
   cwd?: string
@@ -12,24 +18,31 @@ interface SpawnOptions {
   env?: { [name: string]: string }
 }
 
+/** @ignore */
 interface InternalSpawnOptions extends SpawnOptions {
   sidecar?: boolean
 }
 
 interface ChildProcess {
+  /** Exit code of the process. `null` if the process was terminated by a signal on Unix. */
   code: number | null
+  /** If the process was terminated by a signal, represents that signal. */
   signal: number | null
+  /** The data that the process wrote to `stdout`. */
   stdout: string
+  /** The data that the process wrote to `stderr`. */
   stderr: string
 }
 
 /**
  * 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 onEvent
- * @param [args] Command args
+ * @ignore
+ * @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 Event handler.
+ * @param args Program arguments.
+ * @param options Configuration for the process spawn.
  * @returns A promise resolving to the process id.
  */
 async function execute(
@@ -55,11 +68,13 @@ async function execute(
 }
 
 class EventEmitter<E> {
+  /** @ignore  */
   // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-  eventListeners: { [key: string]: Array<(arg: any) => void> } = Object.create(
-    null
-  )
+  private eventListeners: {
+    [key: string]: Array<(arg: any) => void>
+  } = Object.create(null)
 
+  /** @ignore  */
   private addEventListener(event: string, handler: (arg: any) => void): void {
     if (event in this.eventListeners) {
       // eslint-disable-next-line security/detect-object-injection
@@ -70,6 +85,7 @@ class EventEmitter<E> {
     }
   }
 
+  /** @ignore  */
   _emit(event: E, payload: any): void {
     if (event in this.eventListeners) {
       // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
@@ -80,6 +96,14 @@ class EventEmitter<E> {
     }
   }
 
+  /**
+   * Listen to an event from the child process.
+   *
+   * @param event The event name.
+   * @param handler The event handler.
+   *
+   * @return The `this` instance for chained calls.
+   */
   on(event: E, handler: (arg: any) => void): EventEmitter<E> {
     this.addEventListener(event as any, handler)
     return this
@@ -87,12 +111,27 @@ class EventEmitter<E> {
 }
 
 class Child {
+  /** The child process `pid`. */
   pid: number
 
   constructor(pid: number) {
     this.pid = pid
   }
 
+  /**
+   * Writes `data` to the `stdin`.
+   *
+   * @param data The message to write, either a string or a byte array.
+   * @example
+   * ```typescript
+   * const command = new Command('node')
+   * const child = await command.spawn()
+   * await child.write('message')
+   * await child.write([0, 1, 2, 3, 4, 5])
+   * ```
+   *
+   * @return A promise indicating the success or failure of the operation.
+   */
   async write(data: string | number[]): Promise<void> {
     return invokeTauriCommand({
       __tauriModule: 'Shell',
@@ -104,6 +143,11 @@ class Child {
     })
   }
 
+  /**
+   * Kills the child process.
+   *
+   * @return A promise indicating the success or failure of the operation.
+   */
   async kill(): Promise<void> {
     return invokeTauriCommand({
       __tauriModule: 'Shell',
@@ -115,14 +159,42 @@ class Child {
   }
 }
 
+/**
+ * The entry point for spawning child processes.
+ * It emits the `close` and `error` events.
+ * @example
+ * ```typescript
+ * const command = new Command('node')
+ * command.on('close', data => {
+ *   console.log(`command finished with code ${data.code} and signal ${data.signal}`)
+ * })
+ * command.on('error', error => console.error(`command error: "${error}"`))
+ * command.stdout.on('data', line => console.log(`command stdout: "${line}"`))
+ * command.stderr.on('data', line => console.log(`command stderr: "${line}"`))
+ *
+ * const child = await command.spawn()
+ * console.log('pid:', child.pid)
+ * ```
+ */
 class Command extends EventEmitter<'close' | 'error'> {
-  program: string
-  args: string[]
-  options: InternalSpawnOptions
-  stdout = new EventEmitter<'data'>()
-  stderr = new EventEmitter<'data'>()
-  pid: number | null = null
+  /** @ignore Program to execute. */
+  private readonly program: string
+  /** @ignore Program arguments */
+  private readonly args: string[]
+  /** @ignore Spawn options. */
+  private readonly options: InternalSpawnOptions
+  /** Event emitter for the `stdout`. Emits the `data` event. */
+  readonly stdout = new EventEmitter<'data'>()
+  /** Event emitter for the `stderr`. Emits the `data` event. */
+  readonly stderr = new EventEmitter<'data'>()
 
+  /**
+   * Creates a new `Command` instance.
+   *
+   * @param program The program to execute.
+   * @param args Program arguments.
+   * @param options Spawn options.
+   */
   constructor(
     program: string,
     args: string | string[] = [],
@@ -135,17 +207,33 @@ class Command extends EventEmitter<'close' | 'error'> {
   }
 
   /**
-   * Creates a command to execute the given sidecar binary.
+   * Creates a command to execute the given sidecar program.
+   * @example
+   * ```typescript
+   * const command = Command.sidecar('my-sidecar')
+   * const output = await command.execute()
+   * ```
    *
-   * @param program Binary name
+   * @param program The program to execute.
+   * @param args Program arguments.
+   * @param options Spawn options.
    * @returns
    */
-  static sidecar(program: string, args: string | string[] = []): Command {
-    const instance = new Command(program, args)
+  static sidecar(
+    program: string,
+    args: string | string[] = [],
+    options?: SpawnOptions
+  ): Command {
+    const instance = new Command(program, args, options)
     instance.options.sidecar = true
     return instance
   }
 
+  /**
+   * Executes the command as a child process, returning a handle to it.
+   *
+   * @return A promise resolving to the child process handle.
+   */
   async spawn(): Promise<Child> {
     return execute(
       (event) => {
@@ -170,6 +258,19 @@ class Command extends EventEmitter<'close' | 'error'> {
     ).then((pid) => new Child(pid))
   }
 
+  /**
+   * Executes the command as a child process, waiting for it to finish and collecting all of its output.
+   * @example
+   * ```typescript
+   * const output = await new Command('echo', 'message').execute()
+   * assert(output.code === 0)
+   * assert(output.signal === null)
+   * assert(output.stdout === 'message')
+   * assert(output.stderr === '')
+   * ```
+   *
+   * @return A promise resolving to the child process output.
+   */
   async execute(): Promise<ChildProcess> {
     return new Promise((resolve, reject) => {
       this.on('error', reject)
@@ -194,16 +295,25 @@ class Command extends EventEmitter<'close' | 'error'> {
   }
 }
 
+/**
+ * Describes the event message received from the command.
+ */
 interface Event<T, V> {
   event: T
   payload: V
 }
 
+/**
+ * Payload for the `Terminated` command event.
+ */
 interface TerminatedPayload {
+  /** Exit code of the process. `null` if the process was terminated by a signal on Unix. */
   code: number | null
+  /** If the process was terminated by a signal, represents that signal. */
   signal: number | null
 }
 
+/** Events emitted by the child process. */
 type CommandEvent =
   | Event<'Stdout', string>
   | Event<'Stderr', string>
@@ -213,9 +323,18 @@ type CommandEvent =
 /**
  * Opens a path or URL with the system's default app,
  * or the one specified with `openWith`.
+ * @example
+ * ```typescript
+ * // opens the given URL on the default browser:
+ * await open('https://github.com/tauri-apps/tauri')
+ * // opens the given URL using `firefox`:
+ * await open('https://github.com/tauri-apps/tauri', 'firefox')
+ * // opens a file using the default program:
+ * await open('/path/to/file')
+ * ```
  *
- * @param path the path or URL to open
- * @param [openWith] the app to open the file or URL with
+ * @param path The path or URL to open.
+ * @param openWith The app to open the file or URL with. Defaults to the system default application for the specified path type.
  * @returns
  */
 async function open(path: string, openWith?: string): Promise<void> {

tooling/api/src/tauri.ts

@@ -2,6 +2,12 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Invoke your custom commands.
+ * @packageDocumentation
+ */
+
+/** @ignore */
 declare global {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   interface Window {
@@ -11,6 +17,7 @@ declare global {
   }
 }
 
+/** @ignore */
 function uid(): string {
   const length = new Int8Array(1)
   window.crypto.getRandomValues(length)
@@ -19,6 +26,12 @@ function uid(): string {
   return array.join('')
 }
 
+/**
+ * Transforms a callback function to a string identifier that can be passed to the backend.
+ * The backend uses the identifier to `eval()` the callback.
+ *
+ * @return A unique identifier associated with the callback function.
+ */
 function transformCallback(
   callback?: (response: any) => void,
   once = false
@@ -40,16 +53,16 @@ function transformCallback(
   return identifier
 }
 
+/** Command arguments. */
 export interface InvokeArgs {
-  mainThread?: boolean
   [key: string]: unknown
 }
 
 /**
  * Sends a message to the backend.
  *
- * @param cmd
- * @param [args]
+ * @param cmd The command name.
+ * @param args The optional arguments to pass to the command.
  * @return A promise resolving or rejecting to the backend response.
  */
 async function invoke<T>(cmd: string, args: InvokeArgs = {}): Promise<T> {

tooling/api/src/updater.ts

@@ -2,6 +2,11 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Customize the auto updater flow.
+ * @packageDocumentation
+ */
+
 import { once, listen, emit, UnlistenFn } from './event'
 
 export type UpdateStatus = 'PENDING' | 'ERROR' | 'DONE' | 'UPTODATE'
@@ -22,6 +27,11 @@ export interface UpdateResult {
   shouldUpdate: boolean
 }
 
+/**
+ * Install the update if there's one available.
+ *
+ * @return A promise indicating the success or failure of the operation.
+ */
 export async function installUpdate(): Promise<void> {
   let unlistenerFn: UnlistenFn | undefined
 
@@ -69,6 +79,11 @@ export async function installUpdate(): Promise<void> {
   })
 }
 
+/**
+ * Checks if an update is available.
+ *
+ * @return Promise resolving to the update status.
+ */
 export async function checkUpdate(): Promise<UpdateResult> {
   let unlistenerFn: UnlistenFn | undefined
 

tooling/api/src/window.ts

@@ -2,14 +2,21 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+/**
+ * Provides APIs to create windows, communicate with other windows and manipulate the current window.
+ * @packageDocumentation
+ */
+
 import { invokeTauriCommand } from './helpers/tauri'
 import { EventCallback, UnlistenFn, listen, once } from './event'
 import { emit } from './helpers/event'
 
+/** @ignore */
 interface WindowDef {
   label: string
 }
 
+/** @ignore */
 declare global {
   interface Window {
     __TAURI__: {
@@ -19,19 +26,35 @@ declare global {
   }
 }
 
+/**
+ * Get a handle to the current webview window. Allows emitting and listening to events from the backend that are tied to the window.
+ *
+ * @return The current window handle.
+ */
 function getCurrent(): WebviewWindowHandle {
   return new WebviewWindowHandle(window.__TAURI__.__currentWindow.label)
 }
 
+/**
+ * Gets metadata for all available webview windows.
+ *
+ * @return The list of webview handles.
+ */
 function getAll(): WindowDef[] {
   return window.__TAURI__.__windows
 }
 
+/** @ignore */
 // events that are emitted right here instead of by the created webview
 const localTauriEvents = ['tauri://created', 'tauri://error']
 
+/**
+ * A webview window handle allows emitting and listening to events from the backend that are tied to the window.
+ */
 class WebviewWindowHandle {
+  /** Window label. */
   label: string
+  /** Local event listeners. */
   listeners: { [key: string]: Array<EventCallback<any>> }
 
   constructor(label: string) {
@@ -41,10 +64,10 @@ class WebviewWindowHandle {
   }
 
   /**
-   * Listen to an event emitted by the webview.
+   * Listen to an event emitted by the backend that is tied to the webview window.
    *
-   * @param event Event name
-   * @param handler Event handler callback
+   * @param event Event name.
+   * @param handler Event handler.
    * @returns A promise resolving to a function to unlisten to the event.
    */
   async listen<T>(
@@ -62,10 +85,10 @@ class WebviewWindowHandle {
   }
 
   /**
-   * Listen to an one-off event emitted by the webview.
+   * Listen to an one-off event emitted by the backend that is tied to the webview window.
    *
-   * @param event Event name
-   * @param handler Event handler callback
+   * @param event Event name.
+   * @param handler Event handler.
    * @returns A promise resolving to a function to unlisten to the event.
    */
   async once<T>(event: string, handler: EventCallback<T>): Promise<UnlistenFn> {
@@ -80,10 +103,10 @@ class WebviewWindowHandle {
   }
 
   /**
-   * Emits an event to the webview.
+   * Emits an event to the backend, tied to the webview window.
    *
-   * @param event Event name
-   * @param [payload] Event payload
+   * @param event Event name.
+   * @param payload Event payload.
    */
   async emit(event: string, payload?: string): Promise<void> {
     if (localTauriEvents.includes(event)) {
@@ -111,6 +134,33 @@ class WebviewWindowHandle {
   }
 }
 
+/**
+ * Create new webview windows and get a handle to existing ones.
+ * @example
+ * ```typescript
+ * // loading embedded asset:
+ * const webview = new WebviewWindow('theUniqueLabel', {
+ *   url: 'path/to/page.html'
+ * })
+ * // alternatively, load a remote URL:
+ * const webview = new WebviewWindow('theUniqueLabel', {
+ *   url: 'https://github.com/tauri-apps/tauri'
+ * })
+ *
+ * webview.once('tauri://created', function () {
+ *  // webview window successfully created
+ * })
+ * webview.once('tauri://error', function (e) {
+ *  // an error happened creating the webview window
+ * })
+ *
+ * // emit an event to the backend
+ * await webview.emit("some event", "data")
+ * // listen to an event from the backend
+ * const unlisten = await webview.listen("event name", e => {})
+ * unlisten()
+ * ```
+ */
 class WebviewWindow extends WebviewWindowHandle {
   constructor(label: string, options: WindowOptions = {}) {
     super(label)
@@ -142,12 +192,15 @@ class WebviewWindow extends WebviewWindowHandle {
   }
 }
 
+/**
+ * Manage the current window object.
+ */
 export class WindowManager {
   /**
    * Updates the window resizable flag.
    *
    * @param resizable
-   * @returns
+   * @returns A promise indicating the success or failure of the operation.
    */
   async setResizable(resizable: boolean): Promise<void> {
     return invokeTauriCommand({
@@ -163,7 +216,7 @@ export class WindowManager {
    * Sets the window title.
    *
    * @param title The new title
-   * @returns
+   * @returns A promise indicating the success or failure of the operation.
    */
   async setTitle(title: string): Promise<void> {
     return invokeTauriCommand({
@@ -178,7 +231,7 @@ export class WindowManager {
   /**
    * Maximizes the window.
    *
-   * @returns
+   * @returns A promise indicating the success or failure of the operation.
    */
   async maximize(): Promise<void> {
     return invokeTauriCommand({
@@ -192,7 +245,7 @@ export class WindowManager {
   /**
    * Unmaximizes the window.
    *
-   * @returns
+   * @returns A promise indicating the success or failure of the operation.
    */
   async unmaximize(): Promise<void> {
     return invokeTauriCommand({
@@ -206,7 +259,7 @@ export class WindowManager {
   /**
    * Minimizes the window.
    *
-   * @returns
+   * @returns A promise indicating the success or failure of the operation.
    */
   async minimize(): Promise<void> {
     return invokeTauriCommand({
@@ -220,7 +273,7 @@ export class WindowManager {
   /**
    * Unminimizes the window.
    *
-   * @returns
+   * @returns A promise indicating the success or failure of the operation.
    */
   async unminimize(): Promise<void> {
     return invokeTauriCommand({
@@ -234,7 +287,7 @@ export class WindowManager {
   /**
    * Sets the window visibility to true.
    *
-   * @returns
+   * @returns A promise indicating the success or failure of the operation.
    */
   async show(): Promise<void> {
     return invokeTauriCommand({
@@ -248,7 +301,7 @@ export class WindowManager {
   /**
    * Sets the window visibility to false.
    *
-   * @returns
+   * @returns A promise indicating the success or failure of the operation.
    */
   async hide(): Promise<void> {
     return invokeTauriCommand({
@@ -262,7 +315,7 @@ export class WindowManager {
   /**
    * Closes the window.
    *
-   * @returns
+   * @returns A promise indicating the success or failure of the operation.
    */
   async close(): Promise<void> {
     return invokeTauriCommand({
@@ -276,8 +329,8 @@ export class WindowManager {
   /**
    * Whether the window should have borders and bars.
    *
-   * @param decorations Whether the window should have borders and bars
-   * @returns
+   * @param decorations Whether the window should have borders and bars.
+   * @returns A promise indicating the success or failure of the operation.
    */
   async setDecorations(decorations: boolean): Promise<void> {
     return invokeTauriCommand({
@@ -292,8 +345,8 @@ export class WindowManager {
   /**
    * Whether the window should always be on top of other windows.
    *
-   * @param alwaysOnTop Whether the window should always be on top of other windows or not
-   * @returns
+   * @param alwaysOnTop Whether the window should always be on top of other windows or not.
+   * @returns A promise indicating the success or failure of the operation.
    */
   async setAlwaysOnTop(alwaysOnTop: boolean): Promise<void> {
     return invokeTauriCommand({
@@ -308,8 +361,8 @@ export class WindowManager {
   /**
    * Sets the window width.
    *
-   * @param width The new window width
-   * @returns
+   * @param width The new window width.
+   * @returns A promise indicating the success or failure of the operation.
    */
   async setWidth(width: number): Promise<void> {
     return invokeTauriCommand({
@@ -324,8 +377,8 @@ export class WindowManager {
   /**
    * Sets the window height.
    *
-   * @param height The new window height
-   * @returns
+   * @param height The new window height.
+   * @returns A promise indicating the success or failure of the operation.
    */
   async setHeight(height: number): Promise<void> {
     return invokeTauriCommand({
@@ -340,9 +393,9 @@ export class WindowManager {
   /**
    * Resizes the window.
    *
-   * @param width The new window width
-   * @param height The new window height
-   * @returns
+   * @param width The new window width.
+   * @param height The new window height.
+   * @returns A promise indicating the success or failure of the operation.
    */
   async resize(width: number, height: number): Promise<void> {
     return invokeTauriCommand({
@@ -358,9 +411,9 @@ export class WindowManager {
   /**
    * Sets the window min size.
    *
-   * @param minWidth The new window min width
-   * @param minHeight The new window min height
-   * @returns
+   * @param minWidth The new window min width.
+   * @param minHeight The new window min height.
+   * @returns A promise indicating the success or failure of the operation.
    */
   async setMinSize(minWidth: number, minHeight: number): Promise<void> {
     return invokeTauriCommand({
@@ -376,9 +429,9 @@ export class WindowManager {
   /**
    * Sets the window max size.
    *
-   * @param maxWidth The new window max width
-   * @param maxHeight The new window max height
-   * @returns
+   * @param maxWidth The new window max width.
+   * @param maxHeight The new window max height.
+   * @returns A promise indicating the success or failure of the operation.
    */
   async setMaxSize(maxWidth: number, maxHeight: number): Promise<void> {
     return invokeTauriCommand({
@@ -394,8 +447,8 @@ export class WindowManager {
   /**
    * Sets the window x position.
    *
-   * @param x The new window x position
-   * @returns
+   * @param x The new window x position.
+   * @returns A promise indicating the success or failure of the operation.
    */
   async setX(x: number): Promise<void> {
     return invokeTauriCommand({
@@ -410,8 +463,8 @@ export class WindowManager {
   /**
    * Sets the window y position.
    *
-   * @param y The new window y position
-   * @returns
+   * @param y The new window y position.
+   * @returns A promise indicating the success or failure of the operation.
    */
   async setY(y: number): Promise<void> {
     return invokeTauriCommand({
@@ -426,9 +479,9 @@ export class WindowManager {
   /**
    * Sets the window position.
    *
-   * @param x The new window x position
-   * @param y The new window y position
-   * @returns
+   * @param x The new window x position.
+   * @param y The new window y position.
+   * @returns A promise indicating the success or failure of the operation.
    */
   async setPosition(x: number, y: number): Promise<void> {
     return invokeTauriCommand({
@@ -444,8 +497,8 @@ export class WindowManager {
   /**
    * Sets the window fullscreen state.
    *
-   * @param fullscreen Whether the window should go to fullscreen or not
-   * @returns
+   * @param fullscreen Whether the window should go to fullscreen or not.
+   * @returns A promise indicating the success or failure of the operation.
    */
   async setFullscreen(fullscreen: boolean): Promise<void> {
     return invokeTauriCommand({
@@ -460,8 +513,8 @@ export class WindowManager {
   /**
    * Sets the window icon.
    *
-   * @param icon Icon bytes or path to the icon file
-   * @returns
+   * @param icon Icon bytes or path to the icon file.
+   * @returns A promise indicating the success or failure of the operation.
    */
   async setIcon(icon: string | number[]): Promise<void> {
     return invokeTauriCommand({
@@ -473,6 +526,11 @@ export class WindowManager {
     })
   }
 
+  /**
+   * Starts dragging the window.
+   *
+   * @return A promise indicating the success or failure of the operation.
+   */
   async startDragging(): Promise<void> {
     return invokeTauriCommand({
       __tauriModule: 'Window',
@@ -483,24 +541,44 @@ export class WindowManager {
   }
 }
 
+/** The manager for the current window. Allows you to manipulate the window object. */
 const appWindow = new WindowManager()
 
+/** Configuration for the window to create. */
 export interface WindowOptions {
+  /**
+   * Remote URL or local file path to open, e.g. `https://github.com/tauri-apps` or `path/to/page.html`.
+   */
   url?: string
+  /** The initial vertical position. Only applies if `y` is also set. */
   x?: number
+  /** The initial horizontal position. Only applies if `x` is also set. */
   y?: number
+  /** The initial width. */
   width?: number
+  /** The initial height. */
   height?: number
+  /** The minimum width. Only applies if `minHeight` is also set. */
   minWidth?: number
+  /** The minimum height. Only applies if `minWidth` is also set. */
   minHeight?: number
+  /** The maximum width. Only applies if `maxHeight` is also set. */
   maxWidth?: number
+  /** The maximum height. Only applies if `maxWidth` is also set. */
   maxHeight?: number
+  /** Whether the window is resizable or not. */
   resizable?: boolean
+  /** Window title. */
   title?: string
+  /** Whether the window is in fullscreen mode or not. */
   fullscreen?: boolean
+  /** Whether the window should be maximized upon creation or not. */
   maximized?: boolean
+  /** Whether the window should be immediately visible upon creation or not. */
   visible?: boolean
+  /** Whether the window should have borders and bars or not. */
   decorations?: boolean
+  /** Whether the window should always be on top of other windows or not. */
   alwaysOnTop?: boolean
 }