From 79dc7d3e50dce9be46780c64d414e6107c30693c Mon Sep 17 00:00:00 2001 From: Yulong Wang Date: Sat, 1 May 2021 22:20:22 -0700 Subject: [PATCH] [js/common] revise TSDoc of some interfaces (#7541) --- js/common/lib/backend-impl.ts | 8 +-- js/common/lib/inference-session.ts | 31 ++++++----- js/common/lib/tensor-utils.ts | 2 +- js/common/lib/tensor.ts | 82 ++++++++++++++++-------------- 4 files changed, 64 insertions(+), 59 deletions(-) diff --git a/js/common/lib/backend-impl.ts b/js/common/lib/backend-impl.ts index 4ca0c47585..f7246ba478 100644 --- a/js/common/lib/backend-impl.ts +++ b/js/common/lib/backend-impl.ts @@ -18,9 +18,9 @@ const backendsSortedByPriority: string[] = []; /** * Register a backend. * - * @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. + * @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. */ export const registerBackend = (name: string, backend: Backend, priority: number): void => { if (backend && typeof backend.init === 'function' && typeof backend.createSessionHandler === 'function') { @@ -49,7 +49,7 @@ export const registerBackend = (name: string, backend: Backend, priority: number /** * Resolve backend by specified hints. * - * @param backendHints a list of execution provider names to lookup. If omitted use registered backends as list. + * @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. */ export const resolveBackend = async(backendHints: readonly string[]): Promise => { diff --git a/js/common/lib/inference-session.ts b/js/common/lib/inference-session.ts index 9447fa1305..8bfe18fba9 100644 --- a/js/common/lib/inference-session.ts +++ b/js/common/lib/inference-session.ts @@ -192,8 +192,8 @@ export interface InferenceSession { /** * Execute the model asynchronously with the given feeds and options. * - * @param feeds Representation of the model input. See type description of `InferenceSession.InputType` for detail. - * @param options Optional. A set of options that controls the behavior of model inference. + * @param feeds - Representation of the model input. See type description of `InferenceSession.InputType` for detail. + * @param options - Optional. A set of options that controls the behavior of model inference. * @returns A promise that resolves to a map, which uses output names as keys and OnnxValue as corresponding values. */ run(feeds: InferenceSession.FeedsType, options?: InferenceSession.RunOptions): Promise; @@ -201,10 +201,10 @@ export interface InferenceSession { /** * Execute the model asynchronously with the given feeds, fetches and options. * - * @param feeds Representation of the model input. See type description of `InferenceSession.InputType` for detail. - * @param fetches Representation of the model output. See type description of `InferenceSession.OutputType` for + * @param feeds - Representation of the model input. See type description of `InferenceSession.InputType` for detail. + * @param fetches - Representation of the model output. See type description of `InferenceSession.OutputType` for * detail. - * @param options Optional. A set of options that controls the behavior of model inference. + * @param options - Optional. A set of options that controls the behavior of model inference. * @returns A promise that resolves to a map, which uses output names as keys and OnnxValue as corresponding values. */ run(feeds: InferenceSession.FeedsType, fetches: InferenceSession.FetchesType, @@ -257,8 +257,8 @@ export interface InferenceSessionFactory { /** * Create a new inference session and load model asynchronously from an ONNX model file. * - * @param uri The URI or file path of the model to load. - * @param options specify configuration for creating a new inference session. + * @param uri - The URI or file path of the model to load. + * @param options - specify configuration for creating a new inference session. * @returns A promise that resolves to an InferenceSession object. */ create(uri: string, options?: InferenceSession.SessionOptions): Promise; @@ -266,8 +266,8 @@ export interface InferenceSessionFactory { /** * Create a new inference session and load model asynchronously from an array bufer. * - * @param buffer An ArrayBuffer representation of an ONNX model. - * @param options specify configuration for creating a new inference session. + * @param buffer - An ArrayBuffer representation of an ONNX model. + * @param options - specify configuration for creating a new inference session. * @returns A promise that resolves to an InferenceSession object. */ create(buffer: ArrayBufferLike, options?: InferenceSession.SessionOptions): Promise; @@ -275,10 +275,10 @@ export interface InferenceSessionFactory { /** * Create a new inference session and load model asynchronously from segment of an array bufer. * - * @param buffer An ArrayBuffer representation of an ONNX model. - * @param byteOffset The beginning of the specified portion of the array buffer. - * @param byteLength The length in bytes of the array buffer. - * @param options specify configuration for creating a new inference session. + * @param buffer - An ArrayBuffer representation of an ONNX model. + * @param byteOffset - The beginning of the specified portion of the array buffer. + * @param byteLength - The length in bytes of the array buffer. + * @param options - specify configuration for creating a new inference session. * @returns A promise that resolves to an InferenceSession object. */ create(buffer: ArrayBufferLike, byteOffset: number, byteLength?: number, options?: InferenceSession.SessionOptions): @@ -287,8 +287,8 @@ export interface InferenceSessionFactory { /** * Create a new inference session and load model asynchronously from a Uint8Array. * - * @param buffer A Uint8Array representation of an ONNX model. - * @param options specify configuration for creating a new inference session. + * @param buffer - A Uint8Array representation of an ONNX model. + * @param options - specify configuration for creating a new inference session. * @returns A promise that resolves to an InferenceSession object. */ create(buffer: Uint8Array, options?: InferenceSession.SessionOptions): Promise; @@ -296,6 +296,5 @@ export interface InferenceSessionFactory { //#endregion } - // eslint-disable-next-line @typescript-eslint/naming-convention export const InferenceSession: InferenceSessionFactory = InferenceSessionImpl; diff --git a/js/common/lib/tensor-utils.ts b/js/common/lib/tensor-utils.ts index 006601a9b8..b83bf02c44 100644 --- a/js/common/lib/tensor-utils.ts +++ b/js/common/lib/tensor-utils.ts @@ -14,7 +14,7 @@ export interface TypedShapeUtils { /** * Create a new tensor with the same data buffer and specified dims. * - * @param dims New dimensions. Size should match the old one. + * @param dims - New dimensions. Size should match the old one. */ reshape(dims: readonly number[]): TypedTensor; } diff --git a/js/common/lib/tensor.ts b/js/common/lib/tensor.ts index bab436ca64..23ef821c84 100644 --- a/js/common/lib/tensor.ts +++ b/js/common/lib/tensor.ts @@ -72,7 +72,13 @@ export declare namespace Tensor { export type Type = keyof DataTypeMap; } +/** + * Represent multi-dimensional arrays to feed to or fetch from model inferencing. + */ export interface TypedTensor extends TypedTensorBase, TypedTensorUtils {} +/** + * Represent multi-dimensional arrays to feed to or fetch from model inferencing. + */ export interface Tensor extends TypedTensorBase, TypedTensorUtils {} export interface TensorConstructor { @@ -80,9 +86,9 @@ export interface TensorConstructor { /** * Construct a new string tensor object from the given type, data and dims. * - * @type Specify the element type. - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param type - Specify the element type. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new(type: 'string', data: Tensor.DataTypeMap['string']|readonly string[], dims?: readonly number[]): TypedTensor<'string'>; @@ -90,18 +96,18 @@ export interface TensorConstructor { /** * Construct a new bool tensor object from the given type, data and dims. * - * @type Specify the element type. - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param type - Specify the element type. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new(type: 'bool', data: Tensor.DataTypeMap['bool']|readonly boolean[], dims?: readonly number[]): TypedTensor<'bool'>; /** * Construct a new numeric tensor object from the given type, data and dims. * - * @type Specify the element type. - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param type - Specify the element type. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new>( type: T, data: Tensor.DataTypeMap[T]|readonly number[], dims?: readonly number[]): TypedTensor; @@ -112,96 +118,96 @@ export interface TensorConstructor { /** * Construct a new float32 tensor object from the given data and dims. * - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new(data: Float32Array, dims?: readonly number[]): TypedTensor<'float32'>; /** * Construct a new int8 tensor object from the given data and dims. * - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new(data: Int8Array, dims?: readonly number[]): TypedTensor<'int8'>; /** * Construct a new uint8 tensor object from the given data and dims. * - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new(data: Uint8Array, dims?: readonly number[]): TypedTensor<'uint8'>; /** * Construct a new uint16 tensor object from the given data and dims. * - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new(data: Uint16Array, dims?: readonly number[]): TypedTensor<'uint16'>; /** * Construct a new int16 tensor object from the given data and dims. * - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new(data: Int16Array, dims?: readonly number[]): TypedTensor<'int16'>; /** * Construct a new int32 tensor object from the given data and dims. * - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new(data: Int32Array, dims?: readonly number[]): TypedTensor<'int32'>; /** * Construct a new int64 tensor object from the given data and dims. * - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new(data: BigInt64Array, dims?: readonly number[]): TypedTensor<'int64'>; /** * Construct a new string tensor object from the given data and dims. * - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new(data: readonly string[], dims?: readonly number[]): TypedTensor<'string'>; /** * Construct a new bool tensor object from the given data and dims. * - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new(data: readonly boolean[], dims?: readonly number[]): TypedTensor<'bool'>; /** * Construct a new float64 tensor object from the given data and dims. * - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new(data: Float64Array, dims?: readonly number[]): TypedTensor<'float64'>; /** * Construct a new uint32 tensor object from the given data and dims. * - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new(data: Uint32Array, dims?: readonly number[]): TypedTensor<'uint32'>; /** * Construct a new uint64 tensor object from the given data and dims. * - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new(data: BigUint64Array, dims?: readonly number[]): TypedTensor<'uint64'>; @@ -212,17 +218,17 @@ export interface TensorConstructor { /** * Construct a new tensor object from the given type, data and dims. * - * @type Specify the element type. - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param type - Specify the element type. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new(type: Tensor.Type, data: Tensor.DataType|readonly number[]|readonly boolean[], dims?: readonly number[]): Tensor; /** * Construct a new tensor object from the given data and dims. * - * @data Specify the tensor data - * @dims Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. + * @param data - Specify the tensor data + * @param dims - Specify the dimension of the tensor. If omitted, a 1-D tensor is assumed. */ new(data: Tensor.DataType, dims?: readonly number[]): Tensor; //#endregion