From d346bd70907ce3394ceb753c5b971cc24d7aa655 Mon Sep 17 00:00:00 2001 From: Erick Zhao Date: Thu, 27 Jun 2024 14:20:56 -0400 Subject: [PATCH] docs: improve API descriptions --- .gitignore | 1 + README.md | 2 - package.json | 2 + src/index.ts | 16 +++++++- src/options.ts | 102 +++++++++++++++++++++++++++++++++---------------- typedoc.json | 4 ++ yarn.lock | 86 +++++++++++++++++++++++++++++++++++++++++ 7 files changed, 178 insertions(+), 35 deletions(-) create mode 100644 typedoc.json diff --git a/.gitignore b/.gitignore index 3c5c090..6331af4 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,4 @@ spec/fixtures/app/Update.exe vendor/7z.dll vendor/7z.exe hook.log +docs diff --git a/README.md b/README.md index 34862a4..aaece6a 100644 --- a/README.md +++ b/README.md @@ -24,8 +24,6 @@ const electronInstaller = require('electron-winstaller'); Then do a build like so.. ```javascript -// NB: Use this syntax within an async function, Node does not have support for -// top-level await as of Node 12. try { await electronInstaller.createWindowsInstaller({ appDirectory: '/tmp/build/my-app-64', diff --git a/package.json b/package.json index d1438bc..99a2c5a 100644 --- a/package.json +++ b/package.json @@ -21,6 +21,7 @@ "scripts": { "install": "node ./script/select-7z-arch.js", "build": "tsc", + "docs": "npx typedoc", "prepublish": "npm run build", "lint": "eslint --ext .ts src spec", "ava": "ava --timeout=60s", @@ -45,6 +46,7 @@ "eslint": "^8.49.0", "eslint-plugin-ava": "^14.0.0", "ts-node": "^10.9.1", + "typedoc": "0.26.2", "typescript": "^4.9.3" }, "optionalDependencies": { diff --git a/src/index.ts b/src/index.ts index a38c734..17c4180 100644 --- a/src/index.ts +++ b/src/index.ts @@ -14,6 +14,14 @@ export { SquirrelWindowsOptions as Options} from './options'; const log = require('debug')('electron-windows-installer:main'); +/** + * A utility function to convert SemVer version strings into NuGet-compatible + * version strings. + * @param version A SemVer version string + * @returns A NuGet-compatible version string + * @see {@link https://semver.org/ | Semantic Versioning specification} + * @see {@link https://learn.microsoft.com/en-us/nuget/concepts/package-versioning?tabs=semver20sort | NuGet versioning specification} + */ export function convertVersion(version: string): string { const parts = version.split('+')[0].split('-'); const mainVersion = parts.shift(); @@ -34,7 +42,13 @@ function checkIfCommandExists(command: string): Promise { }); } - +/** + * This package's main function, which creates a Squirrel.Windows executable + * installer and optionally code-signs the output. + * + * @param options Options for installer generation and signing + * @see {@link https://github.com/Squirrel/Squirrel.Windows | Squirrel.Windows} + */ export async function createWindowsInstaller(options: SquirrelWindowsOptions): Promise { let useMono = false; diff --git a/src/options.ts b/src/options.ts index dd8b7dd..d92c41c 100644 --- a/src/options.ts +++ b/src/options.ts @@ -12,65 +12,82 @@ export interface SquirrelWindowsOptions { /** * The folder path to create the .exe installer in. * - * Defaults to the installer folder at the project root. + * @defaultValue an `installer` folder at the project root. */ outputDirectory?: string; /** * The path to the .nuspectemplate file used by Squirrel.exe. * - * Defaults to the bundled template.nuspectemplate. + * @defaultValue the bundled {@link https://github.com/electron/windows-installer/blob/main/template.nuspectemplate | template.nuspectemplate}. */ nuspecTemplate?: string; /** * The local path to a `.gif` file to display during install. + * + * @defaultValue the bundled {@link https://github.com/electron/windows-installer/blob/main/resources/install-spinner.gif | install-spinner.gif} */ loadingGif?: string; /** - * The authors value for the nuget package metadata. + * The `authors` value for the NuGet package metadata. * - * Defaults to the `author` field from your app's package.json file when unspecified. + * @defaultValue the `author` field from your app's package.json file + * unless {@link SquirrelWindowsOptions.usePackageJson | usePackageJson} is false. + * @see {@link https://learn.microsoft.com/en-us/nuget/reference/nuspec | the Microsoft .nuspec reference}. */ authors?: string; /** - * The owners value for the nuget package metadata. + * The `owners` value for the NuGet package metadata. * - * Defaults to the `authors` field when unspecified. + * @defaultValue the `authors` field from your app's package.json file + * unless {@link SquirrelWindowsOptions.usePackageJson | usePackageJson} is false. + * @see {@link https://learn.microsoft.com/en-us/nuget/reference/nuspec | the Microsoft .nuspec reference}. */ owners?: string; /** - * The copyright value for the nuget package metadata. + * The `copyright` value for the NuGet package metadata. * - * Defaults to a generated copyright with `authors` or `owners`. + * @defaultValue a generated copyright with {@link SquirrelWindowsOptions.authors | authors} + * or {@link SquirrelWindowsOptions.owners | owners}. + * @see {@link https://learn.microsoft.com/en-us/nuget/reference/nuspec | the Microsoft .nuspec reference}. */ copyright?: string; /** * The name of your app's main `.exe` file. * - * This uses the `name` field in your app's package.json file with an added `.exe` extension when unspecified. + * @defaultValue the `name` field in your app's package.json file with an added `.exe` extension + * unless {@link SquirrelWindowsOptions.usePackageJson | usePackageJson} is false. */ exe?: string; /** - * The description value for the nuget package metadata. + * The `description` value for the NuGet package metadata. * - * Defaults to the `description` field from your app's package.json file when unspecified. + * @defaultValue the `description` field from your app's package.json file + * unless {@link SquirrelWindowsOptions.usePackageJson | usePackageJson} is false. + * @see {@link https://learn.microsoft.com/en-us/nuget/reference/nuspec | the Microsoft .nuspec reference}. */ description?: string; /** - * The version value for the nuget package metadata. + * The `version` value for the Nuget package metadata. * - * Defaults to the `version` field from your app's package.json file when unspecified. + * @defaultValue the `version` field from your app's package.json file + * unless {@link SquirrelWindowsOptions.usePackageJson | usePackageJson} is false. + * @see {@link https://learn.microsoft.com/en-us/nuget/reference/nuspec | the Microsoft .nuspec reference}. */ version?: string; /** - * The title value for the nuget package metadata. + * The `title` value for the nuget package metadata. * - * Defaults to the `productName` field and then the `name` field from your app's package.json file when unspecified. + * @defaultValue the `productName` field and then the `name` field from your app's package.json + * file unless {@link SquirrelWindowsOptions.usePackageJson | usePackageJson} is false. + * @see {@link https://learn.microsoft.com/en-us/nuget/reference/nuspec | the Microsoft .nuspec reference}. */ title?: string; /** * Windows Application Model ID (appId). * - * Defaults to the name field in your app's package.json file. + * @defaultValue the `name` field in your app's package.json file + * unless {@link SquirrelWindowsOptions.usePackageJson | usePackageJson} is false. + * @see {@link https://learn.microsoft.com/en-us/windows/win32/shell/appids | Microsoft's Application User Model IDs documentation}. */ name?: string; /** @@ -78,7 +95,8 @@ export interface SquirrelWindowsOptions { * * This is a legacy parameter provided for backwards compatibility. * For more comprehensive support of various codesigning scenarios - * like EV certificates, see the "windowsSign" parameter. + * like EV certificates, see the + * {@link SquirrelWindowsOptions.windowsSign | windowsSign} parameter. */ certificateFile?: string; /** @@ -86,17 +104,20 @@ export interface SquirrelWindowsOptions { * * This is a legacy parameter provided for backwards compatibility. * For more comprehensive support of various codesigning scenarios - * like EV certificates, see the "windowsSign" parameter. + * like EV certificates, see the + * {@link SquirrelWindowsOptions.windowsSign | windowsSign} parameter. */ certificatePassword?: string; /** * Params to pass to signtool. * - * Overrides `certificateFile` and `certificatePassword`. + * Overrides {@link SquirrelWindowsOptions.certificateFile | certificateFile} + * and {@link SquirrelWindowsOptions.certificatePassword | certificatePassword}`. * * This is a legacy parameter provided for backwards compatibility. * For more comprehensive support of various codesigning scenarios - * like EV certificates, see the "windowsSign" parameter. + * like EV certificates, see the + * {@link SquirrelWindowsOptions.windowsSign | windowsSign} parameter. */ signWithParams?: string; /** @@ -106,7 +127,7 @@ export interface SquirrelWindowsOptions { * * Does not accept `file:` URLs. * - * Defaults to the Electron icon. + * @defaultValue the Electron icon. */ iconUrl?: string; /** @@ -115,48 +136,65 @@ export interface SquirrelWindowsOptions { setupIcon?: string; /** * The name to use for the generated Setup.exe file + * @defaultValue the `productName` field from your app's package.json file + * unless {@link SquirrelWindowsOptions.usePackageJson | usePackageJson} is false. */ setupExe?: string; /** * The name to use for the generated Setup.msi file + * @defaultValue the `productName` field from your app's package.json file + * unless {@link SquirrelWindowsOptions.usePackageJson | usePackageJson} is false. */ setupMsi?: string; /** - * Should Squirrel.Windows create an MSI installer? + * Enable this flag to prevent Squirrel.Windows from creating an MSI installer. + * @defaultValue false */ noMsi?: boolean; /** - * Should Squirrel.Windows delta packages? (disable only if necessary, they are a Good Thing) + * Enable this flag to prevent Squirrel.Windows from creating delta packages (disable only if necessary, they are a Good Thing). + * @defaultValue false */ noDelta?: boolean; /** - * A URL to your existing updates. If given, these will be downloaded to create delta updates + * A URL to your existing updates. If given, these will be downloaded to create delta updates. */ remoteReleases?: string; /** - * Authentication token for remote updates + * Authentication token for remote updates using {@link SquirrelWindowsOptions.remoteReleases | remoteReleases} */ remoteToken?: string; - + /** + * Whether or not to infer metadata options from your app's package.json file. + * @defaultValue true + */ usePackageJson?: boolean; - + /** + * Set the required .NET framework version (e.g. `net461`). + */ frameworkVersion?: string; - + /** + * Attempt to create more descriptive installer names using metadata parameters. + * @defaultValue false + */ fixUpPaths?: boolean; - + /** + * Enable this flag to skip setting a custom icon for `Update.exe` + * @defaultValue false + */ skipUpdateIcon?: boolean; /** * Requires Node.js 18 or newer. * - * Sign your app with @electron/windows-sign, allowing for full customization + * Sign your app with `@electron/windows-sign`, allowing for full customization * of the code-signing process - and supports more complicated scenarios like * cloud-hosted EV certificates, custom sign pipelines, and per-file overrides. * It also supports all existing "simple" codesigning scenarios, including * just passing a certificate file and password. * - * Please see https://github.com/@electron/windows-sign for all possible - * configuration options. + * @see {@link https://github.com/electron/windows-sign | @electron/windows-sign documentation} + * for all possible configuration options. */ windowsSign?: SignToolOptions; } diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 0000000..883263c --- /dev/null +++ b/typedoc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://typedoc.org/schema.json", + "entryPoints": ["./src/index.ts"] +} diff --git a/yarn.lock b/yarn.lock index fbdc05b..e90328e 100644 --- a/yarn.lock +++ b/yarn.lock @@ -127,6 +127,11 @@ "@nodelib/fs.scandir" "2.1.5" fastq "^1.6.0" +"@shikijs/core@1.9.1": + version "1.9.1" + resolved "https://registry.yarnpkg.com/@shikijs/core/-/core-1.9.1.tgz#f8c61fb19dbec510fa27f892c441d99b53093e49" + integrity sha512-EmUful2MQtY8KgCF1OkBtOuMcvaZEvmdubhW0UHCGXi21O9dRLeADVCj+k6ZS+de7Mz9d2qixOXJ+GLhcK3pXg== + "@tsconfig/node10@^1.0.7": version "1.0.9" resolved "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.9.tgz" @@ -463,6 +468,13 @@ brace-expansion@^1.1.7: balanced-match "^1.0.0" concat-map "0.0.1" +brace-expansion@^2.0.1: + version "2.0.1" + resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.0.1.tgz#1edc459e0f0c548486ecf9fc99f2221364b9a0ae" + integrity sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA== + dependencies: + balanced-match "^1.0.0" + braces@^3.0.2, braces@~3.0.2: version "3.0.2" resolved "https://registry.npmjs.org/braces/-/braces-3.0.2.tgz" @@ -727,6 +739,11 @@ enhance-visitors@^1.0.0: dependencies: lodash "^4.13.1" +entities@^4.4.0: + version "4.5.0" + resolved "https://registry.yarnpkg.com/entities/-/entities-4.5.0.tgz#5d268ea5e7113ec74c4d033b79ea5a35a488fb48" + integrity sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw== + escalade@^3.1.1: version "3.1.1" resolved "https://registry.npmjs.org/escalade/-/escalade-3.1.1.tgz" @@ -1288,6 +1305,13 @@ levn@^0.4.1: prelude-ls "^1.2.1" type-check "~0.4.0" +linkify-it@^5.0.0: + version "5.0.0" + resolved "https://registry.yarnpkg.com/linkify-it/-/linkify-it-5.0.0.tgz#9ef238bfa6dc70bd8e7f9572b52d369af569b421" + integrity sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ== + dependencies: + uc.micro "^2.0.0" + load-json-file@^7.0.0: version "7.0.1" resolved "https://registry.npmjs.org/load-json-file/-/load-json-file-7.0.1.tgz" @@ -1324,6 +1348,11 @@ lru-cache@^6.0.0: dependencies: yallist "^4.0.0" +lunr@^2.3.9: + version "2.3.9" + resolved "https://registry.yarnpkg.com/lunr/-/lunr-2.3.9.tgz#18b123142832337dd6e964df1a5a7707b25d35e1" + integrity sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow== + make-error@^1.1.1: version "1.3.5" resolved "https://registry.npmjs.org/make-error/-/make-error-1.3.5.tgz" @@ -1336,6 +1365,18 @@ map-age-cleaner@^0.1.3: dependencies: p-defer "^1.0.0" +markdown-it@^14.1.0: + version "14.1.0" + resolved "https://registry.yarnpkg.com/markdown-it/-/markdown-it-14.1.0.tgz#3c3c5992883c633db4714ccb4d7b5935d98b7d45" + integrity sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg== + dependencies: + argparse "^2.0.1" + entities "^4.4.0" + linkify-it "^5.0.0" + mdurl "^2.0.0" + punycode.js "^2.3.1" + uc.micro "^2.1.0" + matcher@^5.0.0: version "5.0.0" resolved "https://registry.npmjs.org/matcher/-/matcher-5.0.0.tgz" @@ -1350,6 +1391,11 @@ md5-hex@^3.0.1: dependencies: blueimp-md5 "^2.10.0" +mdurl@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/mdurl/-/mdurl-2.0.0.tgz#80676ec0433025dd3e17ee983d0fe8de5a2237e0" + integrity sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w== + mem@^9.0.2: version "9.0.2" resolved "https://registry.npmjs.org/mem/-/mem-9.0.2.tgz" @@ -1388,6 +1434,13 @@ minimatch@^3.0.4, minimatch@^3.0.5, minimatch@^3.1.2: dependencies: brace-expansion "^1.1.7" +minimatch@^9.0.4: + version "9.0.5" + resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-9.0.5.tgz#d74f9dd6b57d83d8e98cfb82133b03978bc929e5" + integrity sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow== + dependencies: + brace-expansion "^2.0.1" + minimist@^1.2.8: version "1.2.8" resolved "https://registry.yarnpkg.com/minimist/-/minimist-1.2.8.tgz#c1a464e7693302e082a075cee0c057741ac4772c" @@ -1582,6 +1635,11 @@ pretty-ms@^8.0.0: dependencies: parse-ms "^3.0.0" +punycode.js@^2.3.1: + version "2.3.1" + resolved "https://registry.yarnpkg.com/punycode.js/-/punycode.js-2.3.1.tgz#6b53e56ad75588234e79f4affa90972c7dd8cdb7" + integrity sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA== + punycode@^2.1.0: version "2.1.1" resolved "https://registry.npmjs.org/punycode/-/punycode-2.1.1.tgz" @@ -1673,6 +1731,13 @@ shebang-regex@^3.0.0: resolved "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz" integrity sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A== +shiki@^1.9.0: + version "1.9.1" + resolved "https://registry.yarnpkg.com/shiki/-/shiki-1.9.1.tgz#9d9f553b06e70a9e71b5457622d6f4a5aaf1db27" + integrity sha512-8PDkgb5ja3nfujTjvC4VytL6wGOGCtFAClUb2r3QROevYXxcq+/shVJK5s6gy0HZnjaJgFxd6BpPqpRfqne5rA== + dependencies: + "@shikijs/core" "1.9.1" + signal-exit@^4.0.1: version "4.1.0" resolved "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz" @@ -1839,11 +1904,27 @@ type-fest@^0.20.2: resolved "https://registry.npmjs.org/type-fest/-/type-fest-0.20.2.tgz" integrity sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ== +typedoc@0.26.2: + version "0.26.2" + resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.26.2.tgz#f9538e6e9a081fda1f2416d0ee0d7dfab480cbec" + integrity sha512-q/t+M+PZqhN9gPWLBZ3CCvP+KT8O1tyYkSzEYbcQ6mo89avdIrMlBEl3vfo5BgSzwC6Lbmq0W64E8RkY+eVsLA== + dependencies: + lunr "^2.3.9" + markdown-it "^14.1.0" + minimatch "^9.0.4" + shiki "^1.9.0" + yaml "^2.4.5" + typescript@^4.9.3: version "4.9.5" resolved "https://registry.npmjs.org/typescript/-/typescript-4.9.5.tgz" integrity sha512-1FXk9E2Hm+QzZQ7z+McJiHL4NW1F2EzMu9Nq9i3zAaGqibafqYwCVU6WyWAuyQRRzOlxou8xZSyXLEN8oKj24g== +uc.micro@^2.0.0, uc.micro@^2.1.0: + version "2.1.0" + resolved "https://registry.yarnpkg.com/uc.micro/-/uc.micro-2.1.0.tgz#f8d3f7d0ec4c3dea35a7e3c8efa4cb8b45c9e7ee" + integrity sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A== + universalify@^0.1.0: version "0.1.2" resolved "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz" @@ -1910,6 +1991,11 @@ yallist@^4.0.0: resolved "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz" integrity sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A== +yaml@^2.4.5: + version "2.4.5" + resolved "https://registry.yarnpkg.com/yaml/-/yaml-2.4.5.tgz#60630b206dd6d84df97003d33fc1ddf6296cca5e" + integrity sha512-aBx2bnqDzVOyNKfsysjA2ms5ZlnjSAW2eG3/L5G/CSujfjLJTJsEw1bGw8kCf04KodQWk1pxlGnZ56CRxiawmg== + yargs-parser@^21.1.1: version "21.1.1" resolved "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz"