From eed4cace8b99a2d6a239676d55136d83857613c3 Mon Sep 17 00:00:00 2001 From: Joshua Bell Date: Fri, 8 Nov 2024 17:30:34 -0800 Subject: [PATCH] Editorial: Avoid the wordier "the XYZ argument"; just say "XYZ". Part of https://github.com/webmachinelearning/webnn/issues/783 --- docs/SpecCodingConventions.md | 1 + index.bs | 39 ++++++++++++++++++----------------- tools/lint.mjs | 3 +++ 3 files changed, 24 insertions(+), 19 deletions(-) diff --git a/docs/SpecCodingConventions.md b/docs/SpecCodingConventions.md index 9db2f6fc..40ca45dc 100644 --- a/docs/SpecCodingConventions.md +++ b/docs/SpecCodingConventions.md @@ -129,6 +129,7 @@ Example: * There is an exception to this rule: Referring to WebIDL types is necessary when dealing with unions. In this case, refer to the full WebIDL type, e.g. _If splits is an `unsigned long` ... Otherwise, if splits is a `sequence` ..._ * Do not repeat detaults provided by the WebIDL declaration. * For types like lists that can't be defaulted in WebIDL, define the default when missing as an explicit step. Example: _If options.padding does not exist, set options.padding to « 0, 0, 0, 0 »._ +* When referring to arguments and options in prose, avoid the wordier `the *foo* argument` or `the *bar* value` forms; just use the name alone. ### Internal Algorithms diff --git a/index.bs b/index.bs index 0e955244..bebb1f0d 100644 --- a/index.bs +++ b/index.bs @@ -2440,7 +2440,7 @@ partial dictionary MLOpSupportLimits { interpreted according to the value of *options*.{{MLConv2dOptions/filterLayout}} and *options*.{{MLConv2dOptions/groups}}. - options: an {{MLConv2dOptions}}. The optional parameters of the operation. - **Returns:** an {{MLOperand}}. The output 4-D tensor that contains the convolution result. The output shape is interpreted according to the *options*.{{MLConv2dOptions/inputLayout}} value. More specifically, the spatial dimensions or the sizes of the last two dimensions of the output tensor for the {{MLInputOperandLayout/"nchw"}} input layout can be calculated as follows: + **Returns:** an {{MLOperand}}. The output 4-D tensor that contains the convolution result. The output shape is interpreted according to *options*.{{MLConv2dOptions/inputLayout}}. More specifically, the spatial dimensions or the sizes of the last two dimensions of the output tensor for the {{MLInputOperandLayout/"nchw"}} input layout can be calculated as follows: `outputSize = 1 + (inputSize - (filterSize - 1) * dilation - 1 + beginningPadding + endingPadding) / stride` @@ -2683,7 +2683,7 @@ partial dictionary MLOpSupportLimits { interpreted according to the value of *options*.{{MLConvTranspose2dOptions/filterLayout}} and {{MLConvTranspose2dOptions/groups}}. - options: an optional {{MLConvTranspose2dOptions}}. - **Returns:** an {{MLOperand}}. The output 4-D tensor that contains the transposed convolution result. The output shape is interpreted according to the *options*.{{MLConvTranspose2dOptions/inputLayout}} value. More specifically, unless the *options*.{{MLConvTranspose2dOptions/outputSizes}} values are explicitly specified, the *options*.{{MLConvTranspose2dOptions/outputPadding}} is needed to compute the spatial dimension values of the output tensor as follows: + **Returns:** an {{MLOperand}}. The output 4-D tensor that contains the transposed convolution result. The output shape is interpreted according to *options*.{{MLConvTranspose2dOptions/inputLayout}}. More specifically, unless *options*.{{MLConvTranspose2dOptions/outputSizes}} is explicitly specified, *options*.{{MLConvTranspose2dOptions/outputPadding}} is needed to compute the spatial dimension values of the output tensor as follows: `outputSize = (inputSize - 1) * stride + (filterSize - 1) * dilation + 1 - beginningPadding - endingPadding + outputPadding` @@ -4040,11 +4040,11 @@ partial dictionary MLOpSupportLimits {
: bias :: - The 2-D input bias tensor of shape *[numDirections, 3 * hiddenSize]*. The ordering of the bias vectors in the second dimension of the tensor shape is specified according to the {{MLGruOptions/layout}} argument. + The 2-D input bias tensor of shape *[numDirections, 3 * hiddenSize]*. The ordering of the bias vectors in the second dimension of the tensor shape is specified according to {{MLGruOptions/layout}}. : recurrentBias :: - The 2-D recurrent bias tensor of shape *[numDirections, 3 * hiddenSize]*. The ordering of the bias vectors in the second dimension of the tensor shape is specified according to the {{MLGruOptions/layout}} argument. + The 2-D recurrent bias tensor of shape *[numDirections, 3 * hiddenSize]*. The ordering of the bias vectors in the second dimension of the tensor shape is specified according to {{MLGruOptions/layout}}. : initialHiddenState :: @@ -4075,8 +4075,8 @@ partial dictionary MLOpSupportLimits {
**Arguments:** - input: an {{MLOperand}}. The input 3-D tensor of shape *[steps, batchSize, inputSize]*. - - weight: an {{MLOperand}}. The 3-D input weight tensor of shape *[numDirections, 3 * hiddenSize, inputSize]*. The ordering of the weight vectors in the second dimension of the tensor shape is specified according to the |options|.{{MLGruOptions/layout}} argument. - - recurrentWeight: an {{MLOperand}}. The 3-D recurrent weight tensor of shape *[numDirections, 3 * hiddenSize, hiddenSize]*. The ordering of the weight vectors in the second dimension of the tensor shape is specified according to the |options|.{{MLGruOptions/layout}} argument. + - weight: an {{MLOperand}}. The 3-D input weight tensor of shape *[numDirections, 3 * hiddenSize, inputSize]*. The ordering of the weight vectors in the second dimension of the tensor shape is specified according to |options|.{{MLGruOptions/layout}}. + - recurrentWeight: an {{MLOperand}}. The 3-D recurrent weight tensor of shape *[numDirections, 3 * hiddenSize, hiddenSize]*. The ordering of the weight vectors in the second dimension of the tensor shape is specified according to |options|.{{MLGruOptions/layout}}. - steps: an {{unsigned long}} scalar. The number of time steps in the recurrent network. The value must be greater than 0. - hiddenSize: an {{unsigned long}} scalar. The value of the third dimension of the cell output tensor shape. It indicates the number of features in the hidden state. - options: an optional {{MLGruOptions}}. The optional parameters of the operation. @@ -4357,11 +4357,11 @@ partial dictionary MLOpSupportLimits {
: bias :: - The 1-D input bias tensor of shape *[3 * hiddenSize]*. The ordering of the bias vectors in the second dimension of the tensor shape is specified according to the {{MLGruOptions/layout}} argument. + The 1-D input bias tensor of shape *[3 * hiddenSize]*. The ordering of the bias vectors in the second dimension of the tensor shape is specified according to {{MLGruOptions/layout}}. : recurrentBias :: - The 1-D recurrent bias tensor of shape *[3 * hiddenSize]*. The ordering of the bias vectors in the second dimension of the tensor shape is specified according to the {{MLGruOptions/layout}} argument. + The 1-D recurrent bias tensor of shape *[3 * hiddenSize]*. The ordering of the bias vectors in the second dimension of the tensor shape is specified according to {{MLGruOptions/layout}}. : resetAfter :: @@ -4379,8 +4379,8 @@ partial dictionary MLOpSupportLimits {
**Arguments:** - input: an {{MLOperand}}. The input 2-D tensor of shape *[batchSize, inputSize]*. - - weight: an {{MLOperand}}. The 2-D input weight tensor of shape *[3 * hiddenSize, inputSize]*. The ordering of the weight vectors in the first dimension of the tensor shape is specified according to the *options.layout* argument. - - recurrentWeight: an {{MLOperand}}. The 2-D recurrent weight tensor of shape *[3 * hiddenSize, hiddenSize]*. The ordering of the weight vectors in the first dimension of the tensor shape is specified according to the *options.layout* argument. + - weight: an {{MLOperand}}. The 2-D input weight tensor of shape *[3 * hiddenSize, inputSize]*. The ordering of the weight vectors in the first dimension of the tensor shape is specified according to *options.layout*. + - recurrentWeight: an {{MLOperand}}. The 2-D recurrent weight tensor of shape *[3 * hiddenSize, hiddenSize]*. The ordering of the weight vectors in the first dimension of the tensor shape is specified according to *options.layout*. - hiddenState: an {{MLOperand}}. The 2-D input hidden state tensor of shape *[batchSize, hiddenSize]*. - hiddenSize: an {{unsigned long}} scalar. The value of the second dimension of the output tensor shape. It indicates the number of features in the hidden state. - options: an optional {{MLGruCellOptions}}. The optional parameters of the operation. @@ -5377,7 +5377,7 @@ partial dictionary MLOpSupportLimits { **Arguments:** - input: an {{MLOperand}}. The input 3-D tensor of shape *[steps, batchSize, inputSize]*. - weight: an {{MLOperand}}. The 3-D input weight tensor of shape *[numDirections, 4 * hiddenSize, inputSize]*. The ordering of the weight vectors in the second dimension of the tensor shape is specified according to the |options|.{{MLLstmOptions/layout}}. - - recurrentWeight: an {{MLOperand}}. The 3-D recurrent weight tensor of shape *[numDirections, 4 * hiddenSize, hiddenSize]*. The ordering of the weight vectors in the second dimension of the tensor shape is specified according to the |options|.{{MLLstmOptions/layout}} argument. + - recurrentWeight: an {{MLOperand}}. The 3-D recurrent weight tensor of shape *[numDirections, 4 * hiddenSize, hiddenSize]*. The ordering of the weight vectors in the second dimension of the tensor shape is specified according to |options|.{{MLLstmOptions/layout}}. - steps: an {{unsigned long}} scalar. The number of time steps in the recurrent network. The value must be greater than 0. - hiddenSize: an {{unsigned long}} scalar. The value of the third dimension of the cell output tensor shape. It indicates the number of features in the hidden state. - options: an optional {{MLLstmOptions}}. The optional parameters of the operation. @@ -5713,11 +5713,11 @@ partial dictionary MLOpSupportLimits {
: bias :: - The 1-D input bias tensor of shape *[4 * hiddenSize]*. The ordering of the bias vectors in the first dimension of the tensor shape is specified according to the {{MLLstmCellOptions/layout}} argument. + The 1-D input bias tensor of shape *[4 * hiddenSize]*. The ordering of the bias vectors in the first dimension of the tensor shape is specified according to {{MLLstmCellOptions/layout}}. : recurrentBias :: - The 1-D recurrent bias tensor of shape *[4 * hiddenSize]*. The ordering of the bias vectors in the first dimension of the tensor shape is specified according to the {{MLLstmCellOptions/layout}} argument. + The 1-D recurrent bias tensor of shape *[4 * hiddenSize]*. The ordering of the bias vectors in the first dimension of the tensor shape is specified according to {{MLLstmCellOptions/layout}}. : peepholeWeight :: @@ -5735,8 +5735,8 @@ partial dictionary MLOpSupportLimits {
**Arguments:** - input: an {{MLOperand}}. The input 2-D tensor of shape *[batchSize, inputSize]*. - - weight: an {{MLOperand}}. The 2-D input weight tensor of shape *[4 * hiddenSize, inputSize]*. The ordering of the weight vectors in the first dimension of the tensor shape is specified according to the *options.layout* argument. - - recurrentWeight: an {{MLOperand}}. The 2-D recurrent weight tensor of shape *[4 * hiddenSize, hiddenSize]*. The ordering of the weight vectors in the first dimension of the tensor shape is specified according to the *options.layout* argument. + - weight: an {{MLOperand}}. The 2-D input weight tensor of shape *[4 * hiddenSize, inputSize]*. The ordering of the weight vectors in the first dimension of the tensor shape is specified according to *options.layout*. + - recurrentWeight: an {{MLOperand}}. The 2-D recurrent weight tensor of shape *[4 * hiddenSize, hiddenSize]*. The ordering of the weight vectors in the first dimension of the tensor shape is specified according to *options.layout*. - hiddenState: an {{MLOperand}}. The 2-D input hidden state tensor of shape *[batchSize, hiddenSize]*. - cellState: an {{MLOperand}}. The 2-D input cell state tensor of shape *[batchSize, hiddenSize]*. - hiddenSize: an {{unsigned long}} scalar. The value of the second dimension of the output tensor shape. It indicates the number of features in the hidden state. @@ -6614,7 +6614,7 @@ partial dictionary MLOpSupportLimits {
### Reduction operations ### {#api-mlgraphbuilder-reduce} -Reduce the input tensor along all dimensions, or along the axes specified in the {{MLReduceOptions/axes}} array parameter. For each specified axis, the dimension with that index is reduced, i.e. the resulting tensor will not contain it, unless the {{MLReduceOptions/keepDimensions}} option is specified. The values of the resulting tensor are calculated using the specified reduction function that takes as parameters all the input values across the reduced dimensions. +Reduce the input tensor along all dimensions, or along the axes specified in the {{MLReduceOptions/axes}} array parameter. For each specified axis, the dimension with that index is reduced, i.e. the resulting tensor will not contain it, unless {{MLReduceOptions/keepDimensions}} is specified. The values of the resulting tensor are calculated using the specified reduction function that takes as parameters all the values across the reduced dimensions.