docs: typedoc improvements (#1734)

package.json

@@ -68,7 +68,7 @@
     "nyc": "^15.0.0",
     "pkg-up": "^4.0.0",
     "sinon": "^18.0.0",
-    "typedoc": "^0.25.4",
+    "typedoc": "~0.25.4",
     "typescript": "^5.2.2"
   },
   "engines": {
@@ -83,7 +83,7 @@
     "postbuild": "copyfiles -f ./temp/targets.js ./src",
     "coverage": "nyc ava test/index.js",
     "coverage:report": "nyc report --reporter=text-lcov > coverage.lcov",
-    "docs:build": "node test/ci/build_docs.js",
+    "docs:build": "npx typedoc",
     "lint": "eslint .",
     "prepublish": "npm run build",
     "pretest": "npm run build",

src/packager.ts

@@ -192,7 +192,7 @@ async function packageAllSpecifiedCombos(opts: Options, archs: SupportedArch[],
  * - finds or downloads the correct release of Electron
  * - uses that version of Electron to create a app in `<out>/<appname>-<platform>-<arch>`
  *
- * Short example:
+ * @example
  *
  * ```javascript
  * const packager = require('@electron/packager')

src/types.ts

@@ -15,6 +15,9 @@ import { SignOptions as OSXInternalSignOptions } from '@electron/osx-sign/dist/e
 import { SignOptions as WindowsInternalSignOptions } from '@electron/windows-sign/dist/esm/types';
 import type { makeUniversalApp } from '@electron/universal';
 
+/**
+ * @internal
+ */
 export type MakeUniversalOpts = Parameters<typeof makeUniversalApp>[0]
 
 /**
@@ -48,7 +51,7 @@ export type SupportedPlatform = OfficialPlatform | 'all';
 /**
  * A predicate function that, given an absolute file `path`, returns `true` if the file should be
  * ignored, or `false` if the file should be kept. *This does not use any of the default ignored
- * files/directories listed for the {@link ignore} option.*
+ * files/directories listed for the {@link Options.ignore | ignore} option.*
  */
 
 export type IgnoreFunction = (path: string) => boolean;
@@ -61,7 +64,18 @@ export type HookFunctionErrorCallback = (err?: Error | null) => void
  * By default, the functions are called in parallel (via
  * [`Promise.all`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all)).
  * If you need the functions called serially, there is a utility function provided. Please note that
- * **callback-style functions are not supported by `serialHooks`.** For example:
+ * **callback-style functions are not supported by `serialHooks`.**
+ *
+ * @param buildPath - For {@link Options.afterExtract | afterExtract}, the path to the temporary folder where the prebuilt
+ * Electron binary has been extracted to. For {@link Options.afterCopy | afterCopy} and {@link Options.afterPrune | afterPrune}, the path to the
+ * folder where the Electron app has been copied to. For {@link Options.afterComplete | afterComplete}, the final directory
+ * of the packaged application.
+ * @param electronVersion - the version of Electron that is being bundled with the application.
+ * @param platform - The target platform you are packaging for.
+ * @param arch - The target architecture you are packaging for.
+ * @param callback - Must be called once you have completed your actions.
+ *
+ * @example
  *
  * ```javascript
  * const packager = require('@electron/packager')
@@ -90,16 +104,6 @@ export type HookFunctionErrorCallback = (err?: Error | null) => void
  * plugins](https://github.com/electron/packager#plugins).
  */
 export type HookFunction =
-/**
- * @param buildPath - For {@link afterExtract}, the path to the temporary folder where the prebuilt
- * Electron binary has been extracted to. For {@link afterCopy} and {@link afterPrune}, the path to the
- * folder where the Electron app has been copied to. For {@link afterComplete}, the final directory
- * of the packaged application.
- * @param electronVersion - the version of Electron that is being bundled with the application.
- * @param platform - The target platform you are packaging for.
- * @param arch - The target architecture you are packaging for.
- * @param callback - Must be called once you have completed your actions.
- */
   (
     buildPath: string,
     electronVersion: string,
@@ -114,15 +118,21 @@ export type TargetDefinition = {
 }
 export type FinalizePackageTargetsHookFunction = (targets: TargetDefinition[], callback: HookFunctionErrorCallback) => void;
 
-/** See the documentation for [`@electron/osx-sign`](https://npm.im/@electron/osx-sign#opts) for details. */
+/** See the documentation for [`@electron/osx-sign`](https://npm.im/@electron/osx-sign#opts) for details.
+ * @interface
+ */
 export type OsxSignOptions = Omit<OSXInternalSignOptions, 'app' | 'binaries' | 'platform' | 'version'>;
 
 /**
  * See the documentation for [`@electron/universal`](https://github.com/electron/universal)
  * for details.
+ * @interface
  */
 export type OsxUniversalOptions = Omit<MakeUniversalOpts, 'x64AppPath' | 'arm64AppPath' | 'outAppPath' | 'force'>
 
+/**
+ * @internal
+ */
 export type IgnoreFunc = (platform: string, arch: string) => boolean;
 
 /**
@@ -256,7 +266,7 @@ export interface Options {
    * Arbitrary combinations of individual architectures are also supported via a comma-delimited
    * string or array of strings. The non-`all` values correspond to the architecture names used
    * by [Electron releases](https://github.com/electron/electron/releases). This value
-   * is not restricted to the official set if [[download|`download.mirrorOptions`]] is set.
+   * is not restricted to the official set if {@link download|`download.mirrorOptions`} is set.
    *
    * Defaults to the arch of the host computer running Electron Packager.
    *
@@ -417,7 +427,7 @@ export interface Options {
    *   to show up in the dock/window list.* Setting the icon in the file manager is not currently supported.
    *
    * If the file extension is omitted, it is auto-completed to the correct extension based on the
-   * platform, including when [[platform|`platform: 'all'`]] is in effect.
+   * platform, including when {@link platform |`platform: 'all'`} is in effect.
    */
   icon?: string;
   /**
@@ -506,7 +516,7 @@ export interface Options {
    *
    * The official non-`all` values correspond to the platform names used by [Electron
    * releases](https://github.com/electron/electron/releases). This value is not restricted to
-   * the official set if [[download|`download.mirrorOptions]] is set.
+   * the official set if {@link download|`download.mirrorOptions`} is set.
    *
    * Defaults to the platform of the host computer running Electron Packager.
    *
@@ -516,7 +526,7 @@ export interface Options {
    * - `mas` (macOS, specifically for submitting to the Mac App Store)
    * - `win32`
    */
-  platform?: PlatformOption | PlatformOption[];
+  platform?: TargetPlatform | 'all' | Array<TargetPlatform | 'all'>;
   /**
    * The path to a prebuilt ASAR file.
    *
@@ -569,7 +579,7 @@ export interface Options {
    * Valid properties are the [Cocoa keys for MacOS](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html)
    * of the pattern `NS(.*)UsageDescription`, where the captured group is the key to use.
    *
-   * Example:
+   * @example
    *
    * ```javascript
    * {
@@ -598,16 +608,25 @@ export interface Options {
   windowsSign?: true | WindowsSignOptions;
 }
 
+/**
+ * @internal
+ */
 interface OptionsWithRequiredArchAndPlatform extends Options {
   arch: Exclude<Options['arch'], undefined>;
   platform: Exclude<Options['platform'], undefined>;
 }
 
+/**
+ * @internal
+ */
 export interface DownloadOptions extends OptionsWithRequiredArchAndPlatform {
   artifactName: string;
   version: string;
 }
 
+/**
+ * @internal
+ */
 export interface ComboOptions extends Options {
   arch: OptionsWithRequiredArchAndPlatform['arch']
   platform: OptionsWithRequiredArchAndPlatform['platform']

typedoc.json

@@ -0,0 +1,14 @@
+{
+  "entryPoints": ["src/index.ts"],
+  "out": "./typedoc",
+  "excludeInternal": true,
+  "sort": ["kind", "required-first", "alphabetical"],
+  "externalSymbolLinkMappings": {
+    "@electron/notarize": {
+      "NotaryToolCredentials": "https://packages.electronjs.org/notarize/main/types/NotaryToolCredentials.html"
+    },
+    "@electron/get": {
+      "ElectronDownloadRequestOptions": "https://github.com/electron/get/blob/79dab2b26df3a6841062b676f11d3e7bb1f8995e/src/types.ts#L57"
+    }
+  }
+}

yarn.lock

@@ -4549,7 +4549,7 @@ typedarray-to-buffer@^3.1.5:
   dependencies:
     is-typedarray "^1.0.0"
 
-typedoc@^0.25.4:
+typedoc@~0.25.4:
   version "0.25.13"
   resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.25.13.tgz#9a98819e3b2d155a6d78589b46fa4c03768f0922"
   integrity sha512-pQqiwiJ+Z4pigfOnnysObszLiU3mVLWAExSPf+Mu06G/qsc3wzbuM56SZQvONhHLncLUhYzOVkjFFpFfL5AzhQ==