[js/api] add typedoc and revise comments (#9077)

* [js/api] add typedoc and revise comments * update document * fix lint error * use config file for typedoc
2026-07-30 20:18:08 +00:00 · 2021-09-20 17:54:46 -07:00 · 2021-09-20 17:54:46 -07:00 · 49b329e266
commit 49b329e266
parent 750e2e0481
11 changed files with 247 additions and 14 deletions
--- a/js/README.md
+++ b/js/README.md
@ -93,6 +93,16 @@ Following features are included in `onnxruntime-common`:
 - `Tensor`/`OnnxValue` interfaces, implementation and a set of utility functions
 - `Backend` interfaces and a set of functions for backend registration

+### Generate API reference document
+
+Use following command in folder `<ORT_ROOT>/js/common` to generate API reference document:
+
+```
+npx typedoc
+```
+
+Document will be generated in folder `<ORT_ROOT>/js/common/docs`.
+
 ## onnxruntime-node

 > language: typescript/C++
--- a/js/common/.gitignore
+++ b/js/common/.gitignore
@ -1,4 +1,5 @@
 node_modules/
 dist/
+docs/

 tsconfig.tsbuildinfo
--- a/js/common/.npmignore
+++ b/js/common/.npmignore
@ -1,6 +1,7 @@
 /.vscode/

 webpack.config.js
+typedoc.json
 tsconfig.json
 **/*.tsbuildinfo

--- a/js/common/lib/backend-impl.ts
+++ b/js/common/lib/backend-impl.ts
@ -21,6 +21,8 @@ const backendsSortedByPriority: string[] = [];
 * @param name - the name as a key to lookup as an execution provider.
 * @param backend - the backend object.
 * @param priority - an integer indicating the priority of the backend. Higher number means higher priority.
+ *
+ * @internal
 */
 export const registerBackend = (name: string, backend: Backend, priority: number): void => {
  if (backend && typeof backend.init === 'function' && typeof backend.createSessionHandler === 'function') {
@ -51,6 +53,8 @@ export const registerBackend = (name: string, backend: Backend, priority: number
 *
 * @param backendHints - a list of execution provider names to lookup. If omitted use registered backends as list.
 * @returns a promise that resolves to the backend.
+ *
+ * @internal
 */
 export const resolveBackend = async(backendHints: readonly string[]): Promise<Backend> => {
  const backendNames = backendHints.length === 0 ? backendsSortedByPriority : backendHints;
--- a/js/common/lib/backend.ts
+++ b/js/common/lib/backend.ts
@ -4,6 +4,9 @@
 import {InferenceSession} from './inference-session';
 import {OnnxValue} from './onnx-value';

+/**
+ * @internal
+ */
 export declare namespace SessionHandler {
  type FeedsType = {[name: string]: OnnxValue};
  type FetchesType = {[name: string]: OnnxValue | null};
@ -12,6 +15,8 @@ export declare namespace SessionHandler {

 /**
 * Represent a handler instance of an inference session.
+ *
+ * @internal
 */
 export interface SessionHandler {
  dispose(): Promise<void>;
@ -28,6 +33,8 @@ export interface SessionHandler {

 /**
 * Represent a backend that provides implementation of model inferencing.
+ *
+ * @internal
 */
 export interface Backend {
  /**
--- a/js/common/lib/env.ts
+++ b/js/common/lib/env.ts
@ -15,6 +15,8 @@ export declare namespace Env {
     * to 1, no worker thread will be spawned.
     *
     * This setting is available only when WebAssembly multithread feature is available in current context.
+     *
+     * @defaultValue `0`
     */
    numThreads?: number;

@ -22,12 +24,16 @@ export declare namespace Env {
     * set or get a boolean value indicating whether to enable SIMD. If set to false, SIMD will be forcely disabled.
     *
     * This setting is available only when WebAssembly SIMD feature is available in current context.
+     *
+     * @defaultValue `true`
     */
    simd?: boolean;

    /**
     * Set or get a number specifying the timeout for initialization of WebAssembly backend, in milliseconds. A zero
-     * value indicates no timeout is set. (default is 0)
+     * value indicates no timeout is set.
+     *
+     * @defaultValue `0`
     */
    initTimeout?: number;

@ -39,29 +45,41 @@ export declare namespace Env {

    /**
     * Set or get a boolean value indicating whether to proxy the execution of main thread to a worker thread.
+     *
+     * @defaultValue `false`
     */
    proxy?: boolean;
  }

  export interface WebGLFlags {
    /**
-     * Set or get the WebGL Context ID (webgl or webgl2). Default value is webgl2.
+     * Set or get the WebGL Context ID (webgl or webgl2).
+     *
+     * @defaultValue `'webgl2'`
     */
    contextId?: 'webgl'|'webgl2';
    /**
     * Set or get the maximum batch size for matmul. 0 means to disable batching.
+     *
+     * @deprecated
     */
    matmulMaxBatchSize?: number;
    /**
-     * Set or get the texture cache mode. Default value is full.
+     * Set or get the texture cache mode.
+     *
+     * @defaultValue `'full'`
     */
    textureCacheMode?: 'initializerOnly'|'full';
    /**
     * Set or get the packed texture mode
+     *
+     * @defaultValue `false`
     */
    pack?: boolean;
    /**
     * Set or get whether enable async download.
+     *
+     * @defaultValue `false`
     */
    async?: boolean;
  }
@ -69,11 +87,15 @@ export declare namespace Env {

 export interface Env {
  /**
-   * set the severity level for logging. If omitted, default is 'warning'
+   * set the severity level for logging.
+   *
+   * @defaultValue `'warning'`
   */
  logLevel?: 'verbose'|'info'|'warning'|'error'|'fatal';
  /**
   * Indicate whether run in debug mode.
+   *
+   * @defaultValue `false`
   */
  debug?: boolean;

--- a/js/common/lib/index.ts
+++ b/js/common/lib/index.ts
@ -1,6 +1,22 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.

+/**
+ * # ONNX Runtime JavaScript API
+ *
+ * ONNX Runtime JavaScript API is a unified API for all JavaScript usages, including the following NPM packages:
+ *
+ * - [onnxruntime-node](https://www.npmjs.com/package/onnxruntime-node)
+ * - [onnxruntime-web](https://www.npmjs.com/package/onnxruntime-web)
+ * - [onnxruntime-react-native](https://www.npmjs.com/package/onnxruntime-react-native)
+ *
+ * See also:
+ * - [Get Started](https://onnxruntime.ai/docs/get-started/with-javascript.html)
+ * - [Inference examples](https://github.com/microsoft/onnxruntime-inference-examples/tree/main/js)
+ *
+ * @packageDocumentation
+ */
+
 export * from './backend';
 export * from './env';
 export * from './inference-session';
--- a/js/common/lib/inference-session.ts
+++ b/js/common/lib/inference-session.ts
@ -24,7 +24,8 @@ export declare namespace InferenceSession {
   * - An array of string indicating the output names.
   * - An object that use output names as keys and OnnxValue or null as corresponding values.
   *
-   * REMARK: different from input argument, in output, OnnxValue is optional. If an OnnxValue is present it will be
+   * @remark
+   * different from input argument, in output, OnnxValue is optional. If an OnnxValue is present it will be
   * used as a pre-allocated value by the inference engine; if omitted, inference engine will allocate buffer
   * internally.
   */
@ -134,8 +135,9 @@ export declare namespace InferenceSession {
     * https://github.com/microsoft/onnxruntime/blob/master/include/onnxruntime/core/session/
     * onnxruntime_session_options_config_keys.h
     *
-     * In example,
+     * This setting is available only in WebAssembly backend. Will support Node.js binding and react-native later
     *
+     * @example
     * ```js
     * extra: {
     *   session: {
@ -147,8 +149,6 @@ export declare namespace InferenceSession {
     *   }
     * }
     * ```
-     *
-     * This setting is available only in WebAssembly backend. Will support Node.js binding and react-native later
     */
    extra?: Record<string, unknown>;
  }
@ -156,7 +156,7 @@ export declare namespace InferenceSession {
  //#region execution providers

  // Currently, we have the following backends to support execution providers:
-  // Backend Node.js binding: supports "cpu" and "cuda".
+  // Backend Node.js binding: supports 'cpu' and 'cuda'.
  // Backend WebAssembly: supports 'wasm'.
  // Backend ONNX.js: supports 'webgl'.
  interface ExecutionProviderOptionMap {
@ -233,7 +233,9 @@ export declare namespace InferenceSession {
     * https://github.com/microsoft/onnxruntime/blob/master/include/onnxruntime/core/session/
     * onnxruntime_run_options_config_keys.h
     *
-     * In example,
+     * This setting is available only in WebAssembly backend. Will support Node.js binding and react-native later
+     *
+     * @example
     *
     * ```js
     * extra: {
@ -242,8 +244,6 @@ export declare namespace InferenceSession {
     *   }
     * }
     * ```
-     *
-     * This setting is available only in WebAssembly backend. Will support Node.js binding and react-native later
     */
    extra?: Record<string, unknown>;
  }
--- a/js/common/package-lock.json
+++ b/js/common/package-lock.json
@ -260,6 +260,22 @@
        "color-convert": "^2.0.1"
      }
    },
+    "balanced-match": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
+      "dev": true
+    },
+    "brace-expansion": {
+      "version": "1.1.11",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
+      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "dev": true,
+      "requires": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
    "braces": {
      "version": "3.0.2",
      "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.2.tgz",
@ -348,6 +364,12 @@
      "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==",
      "dev": true
    },
+    "concat-map": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
+      "integrity": "sha1-2Klr13/Wjfd5OnMDajug1UBdR3s=",
+      "dev": true
+    },
    "cross-spawn": {
      "version": "7.0.3",
      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.3.tgz",
@ -486,6 +508,12 @@
        "path-exists": "^4.0.0"
      }
    },
+    "fs.realpath": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
+      "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8=",
+      "dev": true
+    },
    "function-bind": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.1.tgz",
@ -498,6 +526,20 @@
      "integrity": "sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg==",
      "dev": true
    },
+    "glob": {
+      "version": "7.1.7",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-7.1.7.tgz",
+      "integrity": "sha512-OvD9ENzPLbegENnYP5UUfJIirTg4+XwMWGaQfQTY0JenxNvvIKP3U3/tAQSPIu/lHxXYSZmpXlUHeqAIdKzBLQ==",
+      "dev": true,
+      "requires": {
+        "fs.realpath": "^1.0.0",
+        "inflight": "^1.0.4",
+        "inherits": "2",
+        "minimatch": "^3.0.4",
+        "once": "^1.3.0",
+        "path-is-absolute": "^1.0.0"
+      }
+    },
    "glob-to-regexp": {
      "version": "0.4.1",
      "resolved": "https://registry.npmjs.org/glob-to-regexp/-/glob-to-regexp-0.4.1.tgz",
@ -541,6 +583,22 @@
        "resolve-cwd": "^3.0.0"
      }
    },
+    "inflight": {
+      "version": "1.0.6",
+      "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz",
+      "integrity": "sha1-Sb1jMdfQLQwJvJEKEHW6gWW1bfk=",
+      "dev": true,
+      "requires": {
+        "once": "^1.3.0",
+        "wrappy": "1"
+      }
+    },
+    "inherits": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
+      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
+      "dev": true
+    },
    "interpret": {
      "version": "2.2.0",
      "resolved": "https://registry.npmjs.org/interpret/-/interpret-2.2.0.tgz",
@ -612,6 +670,12 @@
      "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==",
      "dev": true
    },
+    "jsonc-parser": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.0.0.tgz",
+      "integrity": "sha512-fQzRfAbIBnR0IQvftw9FJveWiHp72Fg20giDrHz6TdfB12UH/uue0D3hm57UB5KgAVuniLMCaS8P1IMj9NR7cA==",
+      "dev": true
+    },
    "kind-of": {
      "version": "6.0.3",
      "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz",
@ -642,6 +706,18 @@
        "yallist": "^4.0.0"
      }
    },
+    "lunr": {
+      "version": "2.3.9",
+      "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz",
+      "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==",
+      "dev": true
+    },
+    "marked": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/marked/-/marked-3.0.4.tgz",
+      "integrity": "sha512-jBo8AOayNaEcvBhNobg6/BLhdsK3NvnKWJg33MAAPbvTWiG4QBn9gpW1+7RssrKu4K1dKlN+0goVQwV41xEfOA==",
+      "dev": true
+    },
    "merge-stream": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz",
@ -679,6 +755,15 @@
      "integrity": "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==",
      "dev": true
    },
+    "minimatch": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz",
+      "integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==",
+      "dev": true,
+      "requires": {
+        "brace-expansion": "^1.1.7"
+      }
+    },
    "neo-async": {
      "version": "2.6.2",
      "resolved": "https://registry.npmjs.org/neo-async/-/neo-async-2.6.2.tgz",
@ -700,6 +785,15 @@
        "path-key": "^3.0.0"
      }
    },
+    "once": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
+      "integrity": "sha1-WDsap3WWHUsROsF9nFC6753Xa9E=",
+      "dev": true,
+      "requires": {
+        "wrappy": "1"
+      }
+    },
    "onetime": {
      "version": "5.1.2",
      "resolved": "https://registry.npmjs.org/onetime/-/onetime-5.1.2.tgz",
@ -709,6 +803,32 @@
        "mimic-fn": "^2.1.0"
      }
    },
+    "onigasm": {
+      "version": "2.2.5",
+      "resolved": "https://registry.npmjs.org/onigasm/-/onigasm-2.2.5.tgz",
+      "integrity": "sha512-F+th54mPc0l1lp1ZcFMyL/jTs2Tlq4SqIHKIXGZOR/VkHkF9A7Fr5rRr5+ZG/lWeRsyrClLYRq7s/yFQ/XhWCA==",
+      "dev": true,
+      "requires": {
+        "lru-cache": "^5.1.1"
+      },
+      "dependencies": {
+        "lru-cache": {
+          "version": "5.1.1",
+          "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz",
+          "integrity": "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==",
+          "dev": true,
+          "requires": {
+            "yallist": "^3.0.2"
+          }
+        },
+        "yallist": {
+          "version": "3.1.1",
+          "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",
+          "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==",
+          "dev": true
+        }
+      }
+    },
    "p-limit": {
      "version": "3.1.0",
      "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz",
@ -750,6 +870,12 @@
      "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==",
      "dev": true
    },
+    "path-is-absolute": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
+      "integrity": "sha1-F0uSaHNVNP+8es5r9TpanhtcX18=",
+      "dev": true
+    },
    "path-key": {
      "version": "3.1.1",
      "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
@ -885,6 +1011,17 @@
      "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
      "dev": true
    },
+    "shiki": {
+      "version": "0.9.11",
+      "resolved": "https://registry.npmjs.org/shiki/-/shiki-0.9.11.tgz",
+      "integrity": "sha512-tjruNTLFhU0hruCPoJP0y+B9LKOmcqUhTpxn7pcJB3fa+04gFChuEmxmrUfOJ7ZO6Jd+HwMnDHgY3lv3Tqonuw==",
+      "dev": true,
+      "requires": {
+        "jsonc-parser": "^3.0.0",
+        "onigasm": "^2.2.5",
+        "vscode-textmate": "5.2.0"
+      }
+    },
    "signal-exit": {
      "version": "3.0.3",
      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.3.tgz",
@ -988,6 +1125,19 @@
        "semver": "^7.3.4"
      }
    },
+    "typedoc": {
+      "version": "0.22.3",
+      "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.22.3.tgz",
+      "integrity": "sha512-EOWf9Vf3Vfb/jzBzr87uoLybQw9fx3iyXLUcpQn9F2Ks1/ZJN9iGeBbYRU+VNqrWvV4T+aS7Ife7GFEJUf0ohQ==",
+      "dev": true,
+      "requires": {
+        "glob": "^7.1.7",
+        "lunr": "^2.3.9",
+        "marked": "^3.0.3",
+        "minimatch": "^3.0.4",
+        "shiki": "^0.9.10"
+      }
+    },
    "typescript": {
      "version": "4.2.4",
      "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.2.4.tgz",
@ -1009,6 +1159,12 @@
      "integrity": "sha512-l8lCEmLcLYZh4nbunNZvQCJc5pv7+RCwa8q/LdUx8u7lsWvPDKmpodJAJNwkAhJC//dFY48KuIEmjtd4RViDrA==",
      "dev": true
    },
+    "vscode-textmate": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/vscode-textmate/-/vscode-textmate-5.2.0.tgz",
+      "integrity": "sha512-Uw5ooOQxRASHgu6C7GVvUxisKXfSgW4oFlO+aa+PAkgmH89O3CXxEEzNRNtHSqtXFTl0nAC1uYj0GMSH27uwtQ==",
+      "dev": true
+    },
    "watchpack": {
      "version": "2.1.1",
      "resolved": "https://registry.npmjs.org/watchpack/-/watchpack-2.1.1.tgz",
@ -1114,6 +1270,12 @@
      "integrity": "sha512-JcKqAHLPxcdb9KM49dufGXn2x3ssnfjbcaQdLlfZsL9rH9wgDQjUtDxbo8NE0F6SFvydeu1VhZe7hZuHsB2/pw==",
      "dev": true
    },
+    "wrappy": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
+      "integrity": "sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8=",
+      "dev": true
+    },
    "yallist": {
      "version": "4.0.0",
      "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz",
@ -1127,4 +1289,4 @@
      "dev": true
    }
  }
-}
+}
--- a/js/common/package.json
+++ b/js/common/package.json
@ -18,6 +18,7 @@
  },
  "devDependencies": {
    "ts-loader": "^9.1.2",
+    "typedoc": "^0.22.3",
    "typescript": "^4.2.4",
    "webpack": "^5.36.2",
    "webpack-cli": "^4.7.0"
@ -27,4 +28,4 @@
  "jsdelivr": "dist/ort-common.min.js",
  "unpkg": "dist/ort-common.min.js",
  "module": "dist/lib/index.js"
-}
+}
--- a/js/common/typedoc.json
+++ b/js/common/typedoc.json
@ -0,0 +1,9 @@
+{
+  "entryPoints": [
+    "lib/index.ts"
+  ],
+  "excludeInternal": true,
+  "name": "ONNX Runtime JavaScript API",
+  "readme": "none",
+  "cleanOutputDir": true
+}