Skip to content

Commit c4de3ef

Browse files
inexorabletashfdwr
andauthored
Avoid "sequence" in prose, linkify use in types (#729)
* [Conventions] Avoid "sequence" in prose, linkify use in types Per the spec processing model, algorithms don't usually deal with a sequence<T> type; the JS value has been converted to an Infra list. So try to avoid using that term in prose, especially as it is confusing for recurrent operators which have temporal sequences as well. But do call out an exception: unpacking unions. When used in an IDL type description, though, do linkify it. Fix a few other grammar/link glitches, too. * Delete extra "of" word. * Update index.bs Co-authored-by: Dwayne Robinson <dwayner@microsoft.com> --------- Co-authored-by: Dwayne Robinson <dwayner@microsoft.com>
1 parent 9a80799 commit c4de3ef

2 files changed

Lines changed: 26 additions & 24 deletions

File tree

docs/SpecCodingConventions.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,8 @@ Example:
125125
* Do not include assertions about argument types. This is redundant with Web IDL declaration.
126126
* Do not include steps that test argument types if those types are guaranteed by WebIDL.
127127
* Do not refer to JavaScript or WebIDL types in method steps. Per the spec processing model, by the time a spec algorithm is invoked, JavaScript types (e.g. Numbers, Arrays) have been mapped to WebIDL types (e.g. unsigned longs, sequences) and those have been mapped to Infra types or general concepts (e.g. numbers, lists).
128+
* In particular, avoid using "sequence" in prose, as recurrent operators deal with temporal sequences. Just use "list" in algorithms, or "array" in developer-facing examples.
129+
* 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>` ..._
128130
* Do not repeat detaults provided by the WebIDL declaration.
129131
* 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 »._
130132

index.bs

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -984,7 +984,7 @@ In accordance with the [=ArrayBufferView/write|Web IDL warning=], to prevent the
984984
- <dfn>inputs</dfn>: an {{MLNamedArrayBufferViews}}. The resources of inputs. Will be [=MLNamedArrayBufferViews/transfer|transferred=] if there are no validation errors.
985985
- <dfn>outputs</dfn>: an {{MLNamedArrayBufferViews}}. The pre-allocated resources of required outputs. Will be [=MLNamedArrayBufferViews/transfer|transferred=] if there are no validation errors.
986986

987-
**Returns:** Promise<{{MLComputeResult}}>.
987+
**Returns:** {{Promise}}<{{MLComputeResult}}>.
988988
</div>
989989

990990
Note: Invocations of {{MLContext/compute()}} will fail if any of the {{MLContext/compute(graph, inputs, outputs)/graph}}'s inputs are not provided as {{MLContext/compute(graph, inputs, outputs)/inputs}}, or if any requested {{MLContext/compute(graph, inputs, outputs)/outputs}} do not match the {{MLContext/compute(graph, inputs, outputs)/graph}}'s outputs.
@@ -1029,7 +1029,7 @@ Note: Invocations of {{MLContext/compute()}} will fail if any of the {{MLContext
10291029
const context = await navigator.ml.createContext();
10301030
const builder = new MLGraphBuilder(context);
10311031
// 1. Create a computational graph 'C = 0.2 * A + B'.
1032-
const constant = builder.constant(operandType.dataType(), 0.2);
1032+
const constant = builder.constant(operandType.dataType, 0.2);
10331033
const A = builder.input('A', operandType);
10341034
const B = builder.input('B', operandType);
10351035
const C = builder.add(builder.mul(A, constant), B);
@@ -1232,10 +1232,10 @@ To <dfn for="MLGraphBuilder">validate operand</dfn> given {{MLGraphBuilder}} |bu
12321232
Specifying the option as {{double}} would lose accuracy when passing values over 2<sup>53</sup>, and specifying {{long long}} would disallow values over 2<sup>63</sup>.
12331233
</div>
12341234

1235-
Issue(whatwg/webidl#1388): Support for unions of {{bigint}} and [=numeric types=] new in [[WEBIDL]], and implementation support is also limited. Prototype implementations are encouraged to provide feedback for this approach.
1235+
Issue(whatwg/webidl#1388): Support for unions of {{bigint}} and [=numeric types=] is new in [[WEBIDL]], and implementation support is also limited. Prototype implementations are encouraged to provide feedback for this approach.
12361236

12371237
### {{MLOperand/dataType()}} ### {#api-mloperand-datatype}
1238-
Return a data type of the {{MLOperand}}.
1238+
Returns the data type of the {{MLOperand}}.
12391239

12401240
<div>
12411241
**Returns:** an {{MLOperandDataType}}. The data type of the operand.
@@ -1249,10 +1249,10 @@ Return a data type of the {{MLOperand}}.
12491249
</details>
12501250

12511251
### {{MLOperand/shape()}} ### {#api-mloperand-shape}
1252-
Return a shape of the {{MLOperand}}.
1252+
Returns the shape of the {{MLOperand}}.
12531253

12541254
<div>
1255-
**Returns:** a sequence of {{unsigned long}}. The shape of the operand.
1255+
**Returns:** [=sequence=]<{{unsigned long}}>. The shape of the operand.
12561256
</div>
12571257

12581258
<details open algorithm>
@@ -1380,7 +1380,7 @@ Create a named {{MLOperand}} based on a descriptor, that can be used as an input
13801380
**Arguments:**
13811381
- <dfn>name</dfn>: a [=string=] name of the input.
13821382
- <dfn>descriptor</dfn>: an {{MLOperandDescriptor}} object.
1383-
**Returns:** an {{MLOperand}} object.
1383+
**Returns:** an {{MLOperand}}.
13841384
</div>
13851385

13861386
<details open algorithm>
@@ -1399,7 +1399,7 @@ Create a named {{MLOperand}} based on a descriptor, that can be used as an input
13991399
</details>
14001400

14011401
<div class="note">
1402-
The {{MLGraphBuilder}} API allows creating an {{MLGraph}} without input operands. If the underlying platform doesn't support that, implementations may add a stub input or passing constants as inputs to the graph.
1402+
The {{MLGraphBuilder}} API allows creating an {{MLGraph}} without input operands. If the underlying platform doesn't support that, implementations may add a stub input, or pass constants as inputs to the graph.
14031403
</div>
14041404

14051405
### constant operands ### {#api-mlgraphbuilder-constant}
@@ -1865,7 +1865,7 @@ partial interface MLGraphBuilder {
18651865
</script>
18661866
<div dfn-for="MLGraphBuilder/concat(inputs, axis)" dfn-type=argument>
18671867
**Arguments:**
1868-
- <dfn>inputs</dfn>: a sequence of {{MLOperand}}. All input tensors must have the
1868+
- <dfn>inputs</dfn>: a [=sequence=]<{{MLOperand}}>. All input tensors must have the
18691869
same shape, except for the size of the dimension to concatenate on.
18701870
- <dfn>axis</dfn>: an {{unsigned long}} scalar. The axis that the inputs concatenate along. Its value must be in the range [0, N-1] where N is the [=MLOperand/rank=] of the input tensors.
18711871

@@ -2804,7 +2804,7 @@ partial interface MLGraphBuilder {
28042804
<div dfn-for="MLGraphBuilder/expand(input, newShape)" dfn-type=argument>
28052805
**Arguments:**
28062806
- <dfn>input</dfn>: an {{MLOperand}}. An input tensor
2807-
- <dfn>newShape</dfn>: a sequence of {{unsigned long}}. The new shape the input tensor is expanded to.
2807+
- <dfn>newShape</dfn>: [=sequence=]<{{unsigned long}}>. The new shape the input tensor is expanded to.
28082808

28092809
**Returns:** an {{MLOperand}}. The tensor with expanded size dimensions.
28102810
</div>
@@ -3217,7 +3217,7 @@ partial interface MLGraphBuilder {
32173217
- <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.
32183218
- <dfn>options</dfn>: an optional {{MLGruOptions}}. The optional parameters of the operation.
32193219

3220-
**Returns:** a sequence of {{MLOperand}}. The first element of the sequence is a 3-D tensor of shape *[numDirections, batchSize, hiddenSize]*, the cell output from the last time step of the network. Additionally, if |options|.{{MLGruOptions/returnSequence}} is set to true, the second element is the 4-D output tensor of shape *[steps, numDirections, batchSize, hiddenSize]* containing every cell outputs from each time step in the temporal sequence.
3220+
**Returns:** [=sequence=]<{{MLOperand}}>. The first element is a 3-D tensor of shape *[numDirections, batchSize, hiddenSize]*, the cell output from the last time step of the network. Additionally, if |options|.{{MLGruOptions/returnSequence}} is set to true, the second element is the 4-D output tensor of shape *[steps, numDirections, batchSize, hiddenSize]* containing every cell outputs from each time step in the temporal sequence.
32213221
</div>
32223222

32233223
<details open algorithm>
@@ -4226,7 +4226,7 @@ partial interface MLGraphBuilder {
42264226
- <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.
42274227
- <dfn>options</dfn>: an optional {{MLLstmOptions}}. The optional parameters of the operation.
42284228

4229-
**Returns:** a sequence of {{MLOperand}}. The first element of the sequence is a 3-D tensor of shape *[numDirections, batchSize, hiddenSize]*, the output hidden state from the last time step of the network. The second element is a 3-D tensor of shape *[numDirections, batchSize, hiddenSize]*, the output cell state from the last time step of the network. Additionally, if |options|.{{MLLstmOptions/returnSequence}} is set to true, the third element is the 4-D output tensor of shape *[steps, numDirections, batchSize, hiddenSize]* containing every output from each time step in the temporal sequence.
4229+
**Returns:** [=sequence=]<{{MLOperand}}>. The first element is a 3-D tensor of shape *[numDirections, batchSize, hiddenSize]*, the output hidden state from the last time step of the network. The second element is a 3-D tensor of shape *[numDirections, batchSize, hiddenSize]*, the output cell state from the last time step of the network. Additionally, if |options|.{{MLLstmOptions/returnSequence}} is set to true, the third element is the 4-D output tensor of shape *[steps, numDirections, batchSize, hiddenSize]* containing every output from each time step in the temporal sequence.
42304230
</div>
42314231

42324232
<details open algorithm>
@@ -4490,7 +4490,7 @@ partial interface MLGraphBuilder {
44904490
- <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.
44914491
- <dfn>options</dfn>: an optional {{MLLstmCellOptions}}. The optional parameters of the operation.
44924492

4493-
**Returns:** a sequence of {{MLOperand}}. The first element of the sequence is the output hidden state of the current time step of the recurrent network. The following element is the output cell state. Both elements are 2-D tensors of shape *[batchSize, hiddenSize]*.
4493+
**Returns:** [=sequence=]<{{MLOperand}}>. The first element is the output hidden state of the current time step of the recurrent network. The following element is the output cell state. Both elements are 2-D tensors of shape *[batchSize, hiddenSize]*.
44944494
</div>
44954495

44964496
<details open algorithm>
@@ -4772,8 +4772,8 @@ partial interface MLGraphBuilder {
47724772
<div dfn-for="MLGraphBuilder/pad(input, beginningPadding, endingPadding, options)" dfn-type=argument>
47734773
**Arguments:**
47744774
- <dfn>input</dfn>: an {{MLOperand}}. The input tensor.
4775-
- <dfn>beginningPadding</dfn>: a sequence of {{unsigned long}}. The sequence of unsigned integer values indicating the number of padding values to add at the beginning of each input dimension, of length *N* where *N* is the [=MLOperand/rank=] of the input tensor. For each dimension *d* of *input*, *beginningPadding[d]* indicates how many values to add before the content in that dimension.
4776-
- <dfn>endingPadding</dfn>: a sequence of {{unsigned long}}. The sequence of unsigned integer values indicating the number of padding values to add at the ending of each input dimension, of length *N* where *N* is the [=MLOperand/rank=] of the input tensor. For each dimension *d* of *input*, *endingPadding[d]* indicates how many values to add after the content in that dimension.
4775+
- <dfn>beginningPadding</dfn>: [=sequence=]<{{unsigned long}}>. The number of padding values to add at the beginning of each input dimension, of length *N* where *N* is the [=MLOperand/rank=] of the input tensor. For each dimension *d* of *input*, *beginningPadding[d]* indicates how many values to add before the content in that dimension.
4776+
- <dfn>endingPadding</dfn>: [=sequence=]<{{unsigned long}}>. The number of padding values to add at the ending of each input dimension, of length *N* where *N* is the [=MLOperand/rank=] of the input tensor. For each dimension *d* of *input*, *endingPadding[d]* indicates how many values to add after the content in that dimension.
47774777
- <dfn>options</dfn>: an optional {{MLPadOptions}}. The optional parameters of the operation.
47784778

47794779
**Returns:** an {{MLOperand}}. The padded output tensor. Each dimension of the output tensor can be calculated as follows:
@@ -5434,7 +5434,7 @@ partial interface MLGraphBuilder {
54345434
: <dfn>axes</dfn>
54355435
::
54365436
A list of length 2.
5437-
Specifies the two consecutive dimensions of the input tensor to which the interpolation algorithm applies. The valid values in the sequence are [0, 1], [1, 2] or [2, 3].
5437+
Specifies the two consecutive dimensions of the input tensor to which the interpolation algorithm applies. The valid values are [0, 1], [1, 2] or [2, 3].
54385438
The default value is [2, 3].
54395439
</dl>
54405440

@@ -5492,7 +5492,7 @@ partial interface MLGraphBuilder {
54925492
<div dfn-for="MLGraphBuilder/reshape(input, newShape)" dfn-type=argument>
54935493
**Arguments:**
54945494
- <dfn>input</dfn>: an {{MLOperand}}. The input tensor.
5495-
- <dfn>newShape</dfn>: a sequence of {{unsigned long}}. The shape of the output tensor.
5495+
- <dfn>newShape</dfn>: [=sequence=]<{{unsigned long}}>. The shape of the output tensor.
54965496
The number of elements implied by *newShape* must be the same as the
54975497
number of elements in the input tensor.
54985498

@@ -5604,8 +5604,8 @@ partial interface MLGraphBuilder {
56045604
<div dfn-for="MLGraphBuilder/slice(input, starts, sizes)" dfn-type=argument>
56055605
**Arguments:**
56065606
- <dfn>input</dfn>: an {{MLOperand}}. The input tensor.
5607-
- <dfn>starts</dfn>: a sequence of {{unsigned long}}. The sequence of unsigned integer values indicating the starting index to slice of each input dimension, of length N where N is the [=MLOperand/rank=] of the input tensor. For each dimension *d* of *input*, *starts[d]* indicates the starting index to slice in that dimension. The starting index must be in the range [0, input size - 1] in that dimension.
5608-
- <dfn>sizes</dfn>: a sequence of {{unsigned long}}. The sequence of unsigned integer values indicating the number of elements to slice of each input dimension, of length N where N is the [=MLOperand/rank=] of the input tensor. For each dimension *d* of *input*, *sizes[d]* indicates the number of elements to slice in that dimension. The size must not be 0 and must satisfy the constraint `starting index + size <= input size` in that dimension.
5607+
- <dfn>starts</dfn>: [=sequence=]<{{unsigned long}}>. The starting index to slice of each input dimension, of length N where N is the [=MLOperand/rank=] of the input tensor. For each dimension *d* of *input*, *starts[d]* indicates the starting index to slice in that dimension. The starting index must be in the range [0, input size - 1] in that dimension.
5608+
- <dfn>sizes</dfn>: [=sequence=]<{{unsigned long}}>. The number of elements to slice of each input dimension, of length N where N is the [=MLOperand/rank=] of the input tensor. For each dimension *d* of *input*, *sizes[d]* indicates the number of elements to slice in that dimension. The size must not be 0 and must satisfy the constraint `starting index + size <= input size` in that dimension.
56095609

56105610
**Returns:** an {{MLOperand}}. The output tensor of the same rank as the input tensor with tensor values stripped to the specified starting and ending indices in each dimension.
56115611
</div>
@@ -5843,10 +5843,10 @@ partial interface MLGraphBuilder {
58435843
<div dfn-for="MLGraphBuilder/split(input, splits, options)" dfn-type=argument>
58445844
**Arguments:**
58455845
- <dfn>input</dfn>: an {{MLOperand}}. The input tensor.
5846-
- <dfn>splits</dfn>: an {{unsigned long}} or a sequence of {{unsigned long}}. If an {{unsigned long}}, it specifies the number of output tensors along the axis. The number must evenly divide the dimension size of *input* along *options.axis*. If a sequence of {{unsigned long}}, it specifies the sizes of each output tensor along the *options.axis*. The sum of sizes must equal to the dimension size of *input* along *options.axis*.
5846+
- <dfn>splits</dfn>: an {{unsigned long}} or [=sequence=]<{{unsigned long}}>. If an {{unsigned long}}, it specifies the number of output tensors along the axis. The number must evenly divide the dimension size of *input* along *options.axis*. If a [=sequence=]<{{unsigned long}}>, it specifies the sizes of each output tensor along the *options.axis*. The sum of sizes must equal to the dimension size of *input* along *options.axis*.
58475847
- <dfn>options</dfn>: an optional {{MLSplitOptions}}. The optional parameters of the operation.
58485848

5849-
**Returns:** a sequence of {{MLOperand}}. The splitted output tensors. If *splits* is an {{unsigned long}}, the [=list/size=] of the output sequence equals to *splits*. The shape of each output tensor is the same as *input* except the dimension size of *axis* equals to the quotient of dividing the dimension size of *input* along *axis* by *splits*. If *splits* is a sequence of {{unsigned long}}, the [=list/size=] of the output sequence equals to the [=list/size=] of *splits*. The shape of the i-th output tensor is the same as *input* except along *axis* where the dimension size is *splits[i]*.
5849+
**Returns:** [=sequence=]<{{MLOperand}}>. The split output tensors. If *splits* is an {{unsigned long}}, the [=list/size=] of the output is equal to *splits*. The shape of each output tensor is the same as *input* except the dimension size of *axis* equals to the quotient of dividing the dimension size of *input* along *axis* by *splits*. If *splits* is a [=sequence=]<{{unsigned long}}>, the [=list/size=] of the output equals the [=list/size=] of *splits*. The shape of the i-th output tensor is the same as *input* except along *axis* where the dimension size is *splits[i]*.
58505850
</div>
58515851

58525852
{{MLSplitOptions}} has the following members:
@@ -5867,7 +5867,7 @@ partial interface MLGraphBuilder {
58675867
1. If |splits| is an {{unsigned long}}:
58685868
1. If |input|'s [=MLOperand/shape=][|axis|] % |splits| is not 0, then [=exception/throw=] a {{TypeError}}.
58695869
1. Otherwise, let |splitCount| be |splits|.
5870-
1. If |splits| is a sequence of {{unsigned long}}:
5870+
1. If |splits| is a [=sequence=]<{{unsigned long}}>:
58715871
1. If any of its elements is equal to 0, then [=exception/throw=] a {{TypeError}}.
58725872

58735873
Issue(391): If 0-size dimensions are allowed, revise the above step.
@@ -6003,8 +6003,8 @@ partial interface MLGraphBuilder {
60036003
: <dfn>permutation</dfn>
60046004
::
60056005
The values used to permute the output shape.
6006-
The default value is [N-1, ..., 0], where N is the [=MLOperand/rank=] of the input tensor, e.g. [2,1,0] for a 3-D tensor.
6007-
These default values cause the output to become a transposed tensor of the input. When specified, the number of values in the sequence must be the same as the [=MLOperand/rank=] of the input tensor, and the values in the sequence must be within the range from 0 to N-1 with no two or more same values found in the sequence.
6006+
The default is [N-1, ..., 0], where N is the [=MLOperand/rank=] of the input tensor, e.g. [2,1,0] for a 3-D tensor.
6007+
These default values cause the output to become a transposed tensor of the input. When specified, the number of values must be the same as the [=MLOperand/rank=] of the input tensor, and the values must be within the range from 0 to N-1 with no duplicates.
60086008
</dl>
60096009

60106010
<div dfn-for="MLGraphBuilder/transpose(input, options)" dfn-type=argument>

0 commit comments

Comments
 (0)