From 49b329e26676e4a8f831e6829d4f893f78169f71 Mon Sep 17 00:00:00 2001 From: Yulong Wang Date: Mon, 20 Sep 2021 17:54:46 -0700 Subject: [PATCH] [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 --- js/README.md | 10 ++ js/common/.gitignore | 1 + js/common/.npmignore | 1 + js/common/lib/backend-impl.ts | 4 + js/common/lib/backend.ts | 7 ++ js/common/lib/env.ts | 30 +++++- js/common/lib/index.ts | 16 +++ js/common/lib/inference-session.ts | 16 +-- js/common/package-lock.json | 164 ++++++++++++++++++++++++++++- js/common/package.json | 3 +- js/common/typedoc.json | 9 ++ 11 files changed, 247 insertions(+), 14 deletions(-) create mode 100644 js/common/typedoc.json diff --git a/js/README.md b/js/README.md index f0a4a53f68..a5bd7872b6 100644 --- 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 `/js/common` to generate API reference document: + +``` +npx typedoc +``` + +Document will be generated in folder `/js/common/docs`. + ## onnxruntime-node > language: typescript/C++ diff --git a/js/common/.gitignore b/js/common/.gitignore index 377e649c45..9d573ceeb9 100644 --- a/js/common/.gitignore +++ b/js/common/.gitignore @@ -1,4 +1,5 @@ node_modules/ dist/ +docs/ tsconfig.tsbuildinfo diff --git a/js/common/.npmignore b/js/common/.npmignore index a790389cab..64e6b50c6f 100644 --- a/js/common/.npmignore +++ b/js/common/.npmignore @@ -1,6 +1,7 @@ /.vscode/ webpack.config.js +typedoc.json tsconfig.json **/*.tsbuildinfo diff --git a/js/common/lib/backend-impl.ts b/js/common/lib/backend-impl.ts index bdc11a2379..1d6ea58ddd 100644 --- 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 => { const backendNames = backendHints.length === 0 ? backendsSortedByPriority : backendHints; diff --git a/js/common/lib/backend.ts b/js/common/lib/backend.ts index aabfe0bdc4..3f1bbc9fa7 100644 --- 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; @@ -28,6 +33,8 @@ export interface SessionHandler { /** * Represent a backend that provides implementation of model inferencing. + * + * @internal */ export interface Backend { /** diff --git a/js/common/lib/env.ts b/js/common/lib/env.ts index 1540cb34a9..2369c63612 100644 --- 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; diff --git a/js/common/lib/index.ts b/js/common/lib/index.ts index 278b78cbc5..81d380354b 100644 --- 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'; diff --git a/js/common/lib/inference-session.ts b/js/common/lib/inference-session.ts index 38bd56b5d0..d2e435e1a2 100644 --- 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; } @@ -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; } diff --git a/js/common/package-lock.json b/js/common/package-lock.json index ed9b2386df..450a3be1e0 100644 --- 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 } } -} \ No newline at end of file +} diff --git a/js/common/package.json b/js/common/package.json index 0688374865..7752efce5b 100644 --- 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" -} \ No newline at end of file +} diff --git a/js/common/typedoc.json b/js/common/typedoc.json new file mode 100644 index 0000000000..a86219130d --- /dev/null +++ b/js/common/typedoc.json @@ -0,0 +1,9 @@ +{ + "entryPoints": [ + "lib/index.ts" + ], + "excludeInternal": true, + "name": "ONNX Runtime JavaScript API", + "readme": "none", + "cleanOutputDir": true +}