Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Editorial: Various style and wording tweaks #797

Merged
merged 13 commits into from
Jan 31, 2025
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/SpecCodingConventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<unsigned long>` ..._
* 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
Expand Down
39 changes: 20 additions & 19 deletions index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -2440,7 +2440,7 @@ partial dictionary MLOpSupportLimits {
interpreted according to the value of *options*.{{MLConv2dOptions/filterLayout}} and *options*.{{MLConv2dOptions/groups}}.
- <dfn>options</dfn>: 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`
</div>
Expand Down Expand Up @@ -2683,7 +2683,7 @@ partial dictionary MLOpSupportLimits {
interpreted according to the value of *options*.{{MLConvTranspose2dOptions/filterLayout}} and {{MLConvTranspose2dOptions/groups}}.
- <dfn>options</dfn>: 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`
</div>
Expand Down Expand Up @@ -4040,11 +4040,11 @@ partial dictionary MLOpSupportLimits {
<dl dfn-type=dict-member dfn-for=MLGruOptions>
: <dfn>bias</dfn>
::
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}}.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we format each numDirections and hiddenSize separately? Like [*numDirections*, 3 * *hiddenSize*], same for other occurrences.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right now the coding conventions say When concisely defining a tensor's layout, use the syntax *[ ... ]* which we'd need to revise. More feedback wanted!


: <dfn>recurrentBias</dfn>
::
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}}.

: <dfn>initialHiddenState</dfn>
::
Expand Down Expand Up @@ -4075,8 +4075,8 @@ partial dictionary MLOpSupportLimits {
<div dfn-for="MLGraphBuilder/gru(input, weight, recurrentWeight, steps, hiddenSize, options)" dfn-type=argument>
**Arguments:**
- <dfn>input</dfn>: an {{MLOperand}}. The input 3-D tensor of shape *[steps, batchSize, inputSize]*.
- <dfn>weight</dfn>: 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.
- <dfn>recurrentWeight</dfn>: 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.
- <dfn>weight</dfn>: 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}}.
- <dfn>recurrentWeight</dfn>: 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}}.
- <dfn>steps</dfn>: an {{unsigned long}} scalar. The number of time steps in the recurrent network. The value must be greater than 0.
- <dfn>hiddenSize</dfn>: 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.
- <dfn>options</dfn>: an optional {{MLGruOptions}}. The optional parameters of the operation.
Expand Down Expand Up @@ -4357,11 +4357,11 @@ partial dictionary MLOpSupportLimits {
<dl dfn-type=dict-member dfn-for=MLGruCellOptions>
: <dfn>bias</dfn>
::
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}}.

: <dfn>recurrentBias</dfn>
::
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}}.

: <dfn>resetAfter</dfn>
::
Expand All @@ -4379,8 +4379,8 @@ partial dictionary MLOpSupportLimits {
<div dfn-for="MLGraphBuilder/gruCell(input, weight, recurrentWeight, hiddenState, hiddenSize, options)" dfn-type=argument>
**Arguments:**
- <dfn>input</dfn>: an {{MLOperand}}. The input 2-D tensor of shape *[batchSize, inputSize]*.
- <dfn>weight</dfn>: 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.
- <dfn>recurrentWeight</dfn>: 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.
- <dfn>weight</dfn>: 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*.
- <dfn>recurrentWeight</dfn>: 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*.
- <dfn>hiddenState</dfn>: an {{MLOperand}}. The 2-D input hidden state tensor of shape *[batchSize, hiddenSize]*.
- <dfn>hiddenSize</dfn>: 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.
- <dfn>options</dfn>: an optional {{MLGruCellOptions}}. The optional parameters of the operation.
Expand Down Expand Up @@ -5377,7 +5377,7 @@ partial dictionary MLOpSupportLimits {
**Arguments:**
- <dfn>input</dfn>: an {{MLOperand}}. The input 3-D tensor of shape *[steps, batchSize, inputSize]*.
- <dfn>weight</dfn>: 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}}.
- <dfn>recurrentWeight</dfn>: 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.
- <dfn>recurrentWeight</dfn>: 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}}.
- <dfn>steps</dfn>: an {{unsigned long}} scalar. The number of time steps in the recurrent network. The value must be greater than 0.
- <dfn>hiddenSize</dfn>: 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.
- <dfn>options</dfn>: an optional {{MLLstmOptions}}. The optional parameters of the operation.
Expand Down Expand Up @@ -5713,11 +5713,11 @@ partial dictionary MLOpSupportLimits {
<dl dfn-type=dict-member dfn-for=MLLstmCellOptions>
: <dfn>bias</dfn>
::
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}}.

: <dfn>recurrentBias</dfn>
::
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}}.

: <dfn>peepholeWeight</dfn>
::
Expand All @@ -5735,8 +5735,8 @@ partial dictionary MLOpSupportLimits {
<div dfn-for="MLGraphBuilder/lstmCell(input, weight, recurrentWeight, hiddenState, cellState, hiddenSize, options)" dfn-type=argument>
**Arguments:**
- <dfn>input</dfn>: an {{MLOperand}}. The input 2-D tensor of shape *[batchSize, inputSize]*.
- <dfn>weight</dfn>: 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.
- <dfn>recurrentWeight</dfn>: 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.
- <dfn>weight</dfn>: 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*.
- <dfn>recurrentWeight</dfn>: 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*.
- <dfn>hiddenState</dfn>: an {{MLOperand}}. The 2-D input hidden state tensor of shape *[batchSize, hiddenSize]*.
- <dfn>cellState</dfn>: an {{MLOperand}}. The 2-D input cell state tensor of shape *[batchSize, hiddenSize]*.
- <dfn>hiddenSize</dfn>: 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.
Expand Down Expand Up @@ -6614,7 +6614,7 @@ partial dictionary MLOpSupportLimits {
</div>

### 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.

<script type=idl>
dictionary MLReduceOptions : MLOperatorOptions {
Expand Down Expand Up @@ -6994,7 +6994,7 @@ partial dictionary MLOpSupportLimits {
: <dfn>sizes</dfn>
::
A list of length 2.
Specifies the target sizes for each input dimension from {{MLResample2dOptions/axes}}: *[sizeForFirstAxis, sizeForSecondAxis]*. When the target sizes are specified, the {{MLResample2dOptions/scales}} argument is ignored, since the scaling factor values are derived from the target sizes of the input.
Specifies the target sizes for each input dimension from {{MLResample2dOptions/axes}} : *[sizeForFirstAxis, sizeForSecondAxis]*. When the target sizes are specified, {{MLResample2dOptions/scales}} is ignored, since the scaling factor values are derived from the target sizes of the input.

: <dfn>axes</dfn>
::
Expand Down Expand Up @@ -7098,7 +7098,7 @@ partial dictionary MLOpSupportLimits {

**Returns:** an {{MLOperand}}. The output tensor. The values of the output
tensor are the same as values of the input tensor. The shape of the output
tensor is specified by the *newShape* argument.
tensor is specified by *newShape*.
</div>

<table id=constraints-reshape class='data' link-for="MLGraphBuilder/reshape(input, newShape, options)">
Expand Down Expand Up @@ -7773,7 +7773,8 @@ partial dictionary MLOpSupportLimits {
</div>

### transpose ### {#api-mlgraphbuilder-transpose}
Permute the dimensions of the input tensor according to the *permutation* argument.
Permute the dimensions of the input tensor.

<script type=idl>
dictionary MLTransposeOptions : MLOperatorOptions {
sequence<[EnforceRange] unsigned long> permutation;
Expand Down
3 changes: 3 additions & 0 deletions tools/lint.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,9 @@ for (const match of source.matchAll(/1\. Else/ig)) {
for (const match of text.matchAll(/ not the same as /g)) {
error(`Prefer "not equal to": ${format(match)}`);
}
for (const match of text.matchAll(/\bthe \S+ argument\b/g)) {
error(`Drop 'the' and 'argument': ${format(match)}`);
}

// Look for incorrect use of shape for an MLOperandDescriptor
for (const match of source.matchAll(/(\|\w*desc\w*\|)'s \[=MLOperand\/shape=\]/ig)) {
Expand Down