fix(docs): clean up types and create API documentation website

.gitignore

@@ -9,3 +9,5 @@
 yarn-error.log
 
 tmp
+
+docs

.prettierrc.json

@@ -2,5 +2,6 @@
   "trailingComma": "all",
   "tabWidth": 2,
   "printWidth": 100,
-  "parser": "typescript"
+  "parser": "typescript",
+  "singleQuote": true
 }

package.json

@@ -50,10 +50,12 @@
     "globstar": "^1.0.0",
     "standard": "^17.1.0",
     "tsx": "^3.14.0",
+    "typedoc": "~0.25.13",
     "typescript": "^5.2.2"
   },
   "scripts": {
     "build": "tsc && tsc -p tsconfig.esm.json",
+    "docs": "npx typedoc",
     "lint": "eslint --ext .ts,.js src bin test",
     "test:loader": "globstar -- node --loader tsx --test \"test/**/*.spec.ts\"",
     "test": "globstar -- node --import tsx --test \"test/**/*.spec.ts\"",

src/index.ts

@@ -1,5 +1,25 @@
 import { sign } from './sign';
-import { createSeaSignTool } from './sea';
-import { OptionalHookOptions, OptionalSignToolOptions, SignOptions, SignToolOptions } from './types';
+import { createSeaSignTool, SeaOptions, InternalSeaOptions } from './sea';
+import {
+  HookFunction,
+  OptionalHookOptions,
+  OptionalSignToolOptions,
+  SignOptions,
+  SignToolOptions,
+  SignOptionsForDirectory,
+  SignOptionsForFiles
+} from './types';
 
-export { sign, SignOptions, SignToolOptions, OptionalSignToolOptions, OptionalHookOptions, createSeaSignTool };
+export {
+  sign,
+  SignOptions,
+  SignToolOptions,
+  HookFunction,
+  OptionalSignToolOptions,
+  OptionalHookOptions,
+  createSeaSignTool,
+  SeaOptions,
+  InternalSeaOptions,
+  SignOptionsForDirectory,
+  SignOptionsForFiles
+};

src/sea.ts

@@ -8,19 +8,43 @@ import { spawnPromise } from './spawn';
 import { log } from './utils/log';
 import { SignToolOptions } from './types';
 
-interface SeaOptions {
-  // Full path to the sea. Needs to end with .exe
-  path: string
-  // Optional: A binary to use. Will use the current executable
-  // (process.execPath) by default.
+/**
+ * Options for signing with a Node.js single executable application.
+ *
+ * @category Single executable applications
+ */
+export interface SeaOptions {
+  /**
+   * Full path to the Node.js single executable application. Needs to end with `.exe`.
+   */
+  path: string;
+  /**
+   * A binary to use. Will use the current executable (process.execPath) by default.
+   *
+   * @defaultValue The Node.js {@link https://nodejs.org/api/process.html#processexecpath | `process.execPath`}
+   */
   bin?: string;
-  // Sign options
-  windowsSign: SignToolOptions
+  /**
+   * Options to pass to SignTool.
+   */
+  windowsSign: SignToolOptions;
 }
 
-interface InternalSeaOptions extends Required<SeaOptions> {
-  dir: string
-  filename: string
+/**
+ * This interface represents {@link SeaOptions} with all optional properties
+ * inferred by `@electron/windows-sign` if not passed in by the user.
+ *
+ * @category Single executable applications
+ */
+export interface InternalSeaOptions extends Required<SeaOptions> {
+  /**
+   * Directory of the Node.js single executable application.
+   */
+  dir: string;
+  /**
+   * File name of the Node.js single executable application.
+   */
+  filename: string;
 }
 
 /**
@@ -104,6 +128,8 @@ sign({ ...options, files })
  * This is useful with other tooling that _always_ calls
  * a signtool.exe to sign. Some of those tools cannot be
  * easily configured, but we _can_ override their signtool.exe.
+ *
+ * @category Single executable applications
  */
 export async function createSeaSignTool(options: Partial<SeaOptions> = {}): Promise<InternalSeaOptions> {
   checkCompatibility();

src/sign-with-hook.ts

@@ -32,7 +32,6 @@ function getHookFunction(options: InternalHookOptions): HookFunction {
  * Sign with a hook function, basically letting everyone
  * write completely custom sign logic
  *
- * @export
  * @param {InternalSignOptions} options
  */
 export async function signWithHook(options: InternalSignOptions) {

src/sign.ts

@@ -13,6 +13,8 @@ import { booleanFromEnv } from './utils/parse-env';
  *
  * @param options
  * @returns {Promise<void>}
+ *
+ * @category Sign
  */
 export async function sign(options: SignOptions) {
   const signJavaScript = options.signJavaScript || booleanFromEnv('WINDOWS_SIGN_JAVASCRIPT');

src/types.ts

@@ -1,76 +1,144 @@
-// SHA-1 has been deprecated on Windows since 2016. We'll still dualsign.
-// https://social.technet.microsoft.com/wiki/contents/articles/32288.windows-enforcement-of-sha1-certificates.aspx#Post-February_TwentySeventeen_Plan
+/**
+ * SHA-1 has been deprecated on Windows since 2016. We'll still dualsign.
+ * https://social.technet.microsoft.com/wiki/contents/articles/32288.windows-enforcement-of-sha1-certificates.aspx#Post-February_TwentySeventeen_Plan
+ */
 export const enum HASHES {
   sha1 = 'sha1',
   sha256 = 'sha256',
 }
 
-export type SignOptions = SignOptionsForDirectory | SignOptionsForFiles
+/**
+ * Signing can be either by specifying a directory of files to sign.
+ *
+ * @category Sign
+ */
+export type SignOptions = SignOptionsForDirectory | SignOptionsForFiles;
 
+/**
+ * Options for signing by passing a path to a directory to be codesigned.
+ *
+ * @category Sign
+ */
 export interface SignOptionsForDirectory extends SignToolOptions {
-  // Path to the application directory. We will scan this
-  // directory for any .dll, .exe, .msi, or .node files and
-  // codesign them with signtool.exe
+  /**
+   * Path to the application directory. We will scan this
+   * directory for any `.dll`, `.exe`, `.msi`, or `.node` files and
+   * codesign them with `signtool.exe`.
+   */
   appDirectory: string;
 }
 
+/**
+ * Options for signing by passing an array of files to be codesigned.
+ *
+ * @category Sign
+ */
 export interface SignOptionsForFiles extends SignToolOptions {
-  // Path to files to be signed.
+  /**
+   * Array of paths to files to be codesigned with `signtool.exe`.
+   */
   files: Array<string>;
 }
 
-export interface SignToolOptions extends OptionalSignToolOptions, OptionalHookOptions {
-
-}
+/**
+ * @category Utility
+ */
+export interface SignToolOptions extends OptionalSignToolOptions, OptionalHookOptions {}
 
 export interface InternalSignOptions extends SignOptionsForFiles {}
 
 export interface InternalSignToolOptions extends OptionalSignToolOptions, OptionalHookOptions {
-  certificateFile?: string;
-  certificatePassword?: string;
   signToolPath: string;
   timestampServer: string;
   files: Array<string>;
   hash: HASHES;
   appendSignature?: boolean;
 }
 
+/**
+ * @category Utility
+ */
 export interface OptionalSignToolOptions {
-  // Path to a .pfx code signing certificate. Will use
-  // process.env.WINDOWS_CERTIFICATE_FILE if not provided
+  /**
+   * Path to a `.pfx` code signing certificate.
+   * Will use `process.env.WINDOWS_CERTIFICATE_FILE` if this option is not provided.
+   */
   certificateFile?: string;
-  // Password to said certificate. If you don't provide this,
-  // you need to provide a `signWithParams` option. Will use
-  // process.env.WINDOWS_CERTIFICATE_PASSWORD if not provided
+  /**
+   * Password to {@link certificateFile}. If you don't provide this,
+   * you need to provide the {@link signWithParams} option.
+   * Will use `process.env.WINDOWS_CERTIFICATE_PASSWORD` if this option is not provided.
+   */
   certificatePassword?: string;
-  // Path to a timestamp server. Defaults to http://timestamp.digicert.com
+  /**
+   * Path to a timestamp server.
+   * Will use `process.env.WINDOWS_TIMESTAMP_SERVER` if this option is not provided.
+   *
+   * @defaultValue http://timestamp.digicert.com
+   */
   timestampServer?: string;
-  // Description of the signed content. Will be passed to signtool.exe as /d
+  /**
+   * Description of the signed content. Will be passed to `signtool.exe` as `/d`.
+   */
   description?: string;
-  // URL of the signed content. Will be passed to signtool.exe as /du
+  /**
+   * URL for the expanded description of the signed content. Will be passed to `signtool.exe` as `/du`.
+   */
   website?: string;
-  // Path to signtool.exe. Will use vendor/signtool.exe if not provided
+  /**
+   * Path to the `signtool.exe` used to sign. Will use `vendor/signtool.exe` if not provided.
+   */
   signToolPath?: string;
-  // Additional parameters to pass to signtool.exe.
+  /**
+   * Additional parameters to pass to `signtool.exe`.
+   *
+   * @see Microsoft's {@link https://learn.microsoft.com/en-us/dotnet/framework/tools/signtool-exe SignTool.exe documentation}
+   */
   signWithParams?: string | Array<string>;
-  // Enable debug logging
+  /**
+   * Enables debug logging.
+   *
+   * @defaultValue false
+   */
   debug?: boolean;
-  // Automatically select the best signing certificate, passed as
-  // /a to signtool.exe, on by default
+  /**
+   * Automatically selects the best signing certificate according to SignTool. Will be passed to `signtool.exe` as `/a`.
+   *
+   * @defaultValue true
+   */
   automaticallySelectCertificate?: boolean;
-  // Should we sign JavaScript files? Defaults to false
-  signJavaScript?: boolean
+  /**
+   * Whether or not to sign JavaScript files.
+   *
+   * @defaultValue false
+   */
+  signJavaScript?: boolean;
 }
 
+/**
+ * Custom function that is called sequentially for each file that needs to be signed.
+ *
+ * @param fileToSign Absolute path to the file to sign
+ *
+ * @category Utility
+ */
 export type HookFunction = (fileToSign: string) => void | Promise<void>;
 
+/**
+ * @category Utility
+ */
 export interface OptionalHookOptions {
-  // A hook function called for each file that needs
-  // to be signed.
+  /**
+   * A hook function called for each file that needs to be signed.
+   * Use this for full control over your app's signing logic.
+   * `@electron/windows-sign` will not attempt to sign with SignTool if a custom hook is detected.
+   */
   hookFunction?: HookFunction;
-  // A path to a JavaScript file, exporting a single
-  // function that will be called for each file that
-  // needs to be signed.
+  /**
+   * A path to a JavaScript file, exporting a single function that will be called for each file that needs to be signed.
+   * Use this for full control over your app's signing logic.
+   * `@electron/windows-sign` will not attempt to sign with SignTool if a custom hook is detected.
+   */
   hookModulePath?: string;
 }
 

typedoc.json

@@ -0,0 +1,6 @@
+{
+	"$schema": "https://typedoc.org/schema.json",
+	"entryPoints": ["src/index.ts"],
+	"excludeInternal": true,
+	"navigation": true
+}