From 934220215dcb38331fefd16e9949d0aba953db4c Mon Sep 17 00:00:00 2001 From: Joshua Bell Date: Mon, 11 Nov 2024 09:40:18 -0800 Subject: [PATCH] Editorial: Linkify all argument/option references outside algorithms Part of https://github.com/webmachinelearning/webnn/issues/783 --- docs/SpecCodingConventions.md | 1 + index.bs | 68 +++++++++++++++++------------------ 2 files changed, 35 insertions(+), 34 deletions(-) diff --git a/docs/SpecCodingConventions.md b/docs/SpecCodingConventions.md index 9a5f5e72..a7a653dd 100644 --- a/docs/SpecCodingConventions.md +++ b/docs/SpecCodingConventions.md @@ -97,6 +97,7 @@ Example: * In Web IDL `
` blocks, wrap long lines to avoid horizontal scrollbars. 88 characters seems to be the magic number.
 * Avoid `v` or `|v|` outside of algorithms; Bikeshed interprets these as global variables which can mask errors. Just use `*v*`.
     * Format each term separately; that is, `*splits*[*i*]` not `*splits[i]*`.
+* When referencing an argument in prose steps, link to it rather than just using formatted text e.g. `{{MLGraphBuilder/split(input, splits*, options)/splits}}` rather than `*splits*`.
 
 
 ### Algorithms
diff --git a/index.bs b/index.bs
index ee1be951..5a2a08dd 100644
--- a/index.bs
+++ b/index.bs
@@ -1767,7 +1767,7 @@ partial dictionary MLOpSupportLimits {
         - axis: The dimension to reduce. The value must be in the range [0, N-1] where N is the [=MLOperand/rank=] of the input tensor.
         - options: an optional {{MLArgMinMaxOptions}}. The optional parameters of the operation.
 
-    **Returns:** an {{MLOperand}}. The N-D tensor of the reduced shape. The values must be of type {{MLArgMinMaxOptions/outputDataType}} in the range [0, N-1] where N is the size of the input dimension specified by axis.
+    **Returns:** an {{MLOperand}}. The N-D tensor of the reduced shape. The values must be of type {{MLArgMinMaxOptions/outputDataType}} in the range [0, N-1] where N is the size of the input dimension specified by {{MLGraphBuilder/argMin(input, axis, options)/axis}}.
 
 
 
@@ -1893,7 +1893,7 @@ partial dictionary MLOpSupportLimits {
         - variance: an {{MLOperand}}. The 1-D tensor of the variance values of the input features across the batch whose [=list/size=] is equal to the size of the input dimension denoted by {{MLBatchNormalizationOptions/axis}}.
         - options: an optional {{MLBatchNormalizationOptions}}. Specifies the optional parameters of the operation.
 
-    **Returns:** an {{MLOperand}}. The batch-normalized N-D tensor of the same shape as *input*.
+    **Returns:** an {{MLOperand}}. The batch-normalized N-D tensor of the same shape as {{MLGraphBuilder/batchNormalization(input, mean, variance, options)/input}}.
 

 
 

@@ -2031,7 +2031,7 @@ partial dictionary MLOpSupportLimits {
         - type: an {{MLOperandDataType}}. The target data type.
         - options: an {{MLOperatorOptions}}. Specifies the optional parameters of the operation.
 
-    **Returns:** an {{MLOperand}}. The N-D tensor of the same shape as *input* with each element casted to the target data type.
+    **Returns:** an {{MLOperand}}. The N-D tensor of the same shape as {{MLGraphBuilder/cast(input, type, options)/input}} with each element casted to the target data type.
 

 
 

@@ -2171,7 +2171,7 @@ partial dictionary MLOpSupportLimits {
         - input: an {{MLOperand}}. The input tensor.
         - options: an optional {{MLClampOptions}}. The optional parameters of the operation.
     **Returns:**
-        - an {{MLOperand}}. The output tensor of the same shape as *input*.
+        - an {{MLOperand}}. The output tensor of the same shape as {{MLGraphBuilder/clamp(input, options)/input}}.
 

 
 

@@ -2275,7 +2275,7 @@ partial dictionary MLOpSupportLimits {
         - options: an {{MLOperatorOptions}}. Specifies the optional parameters of the operation.
 
     **Returns:** an {{MLOperand}}. The concatenated tensor of all the inputs along
-    the *axis*. The output tensor has the same shape except on the dimension
+    the {{MLGraphBuilder/concat(inputs, axis, options)/axis}}. The output tensor has the same shape except on the dimension
     that all the inputs concatenated along. The size of that dimension is
     computed as the sum of all the input sizes of the same dimension.
 
@@ -3420,7 +3420,7 @@ partial dictionary MLOpSupportLimits {
         - options: an optional {{MLEluOptions}}. The optional parameters of the operation.
 
     **Returns:**
-        - an {{MLOperand}}. The output tensor of the same shape as *input*.
+        - an {{MLOperand}}. The output tensor of the same shape as {{MLGraphBuilder/elu(input, options)/input}}.
 

 
 

@@ -3590,7 +3590,7 @@ partial dictionary MLOpSupportLimits {
         - indices: an {{MLOperand}}. The indices N-D tensor of the input values to gather. The values must be of type {{MLOperandDataType/"int32"}}, {{MLOperandDataType/"uint32"}} or {{MLOperandDataType/"int64"}}, and must be in the range -N (inclusive) to N (exclusive) where N is the size of the input dimension indexed by {{MLGatherOptions/axis}}, and a negative index means indexing from the end of the dimension.
         - options: an optional {{MLGatherOptions}}. The optional parameters of the operation.
 
-    **Returns:** an {{MLOperand}}. The output N-D tensor of [=MLOperand/rank=] equal to the [=MLOperand/rank=] of *input* + the [=MLOperand/rank=] of *indices* - 1.
+    **Returns:** an {{MLOperand}}. The output N-D tensor of [=MLOperand/rank=] equal to the [=MLOperand/rank=] of {{MLGraphBuilder/gather(input, indices, options)/input}} + the [=MLOperand/rank=] of {{MLGraphBuilder/gather(input, indices, options)/indices}} - 1.
 

@@ -3753,7 +3753,7 @@ partial dictionary MLOpSupportLimits {
         - options: an {{MLOperatorOptions}}. Specifies the optional parameters of the operation.
 
     **Returns:**
-        - an {{MLOperand}}. The output tensor of the same shape as *input*.
+        - an {{MLOperand}}. The output tensor of the same shape as {{MLGraphBuilder/gelu(input, options)/input}}.
 

 
 
 
 

@@ -4632,7 +4632,7 @@ partial dictionary MLOpSupportLimits {
         - options: an optional {{MLHardSigmoidOptions}}. The optional parameters of the operation.
 
     **Returns:**
-        - an {{MLOperand}}. The output tensor of the same shape as *input*.
+        - an {{MLOperand}}. The output tensor of the same shape as {{MLGraphBuilder/hardSigmoid(input, options)/input}}.
 

 
 

@@ -4717,7 +4717,7 @@ partial dictionary MLOpSupportLimits {
         - options: an {{MLOperatorOptions}}. Specifies the optional parameters of the operation.
 
     **Returns:**
-        - an {{MLOperand}}. The output tensor of the same shape as *input*.
+        - an {{MLOperand}}. The output tensor of the same shape as {{MLGraphBuilder/hardSwish(input, options)/input}}.
 

 
 

@@ -4816,11 +4816,11 @@ partial dictionary MLOpSupportLimits {
 

     : scale
     ::
-        The 1-D tensor of the scaling values whose [=list/size=] is equal to the number of channels, i.e. the size of the feature dimension of the input. For example, for an *input* tensor with {{MLInputOperandLayout/"nchw"}} layout, the [=list/size=] is equal to *input*'s [=MLOperand/shape=][1].
+        The 1-D tensor of the scaling values whose [=list/size=] is equal to the number of channels, i.e. the size of the feature dimension of the input. For example, for an {{MLGraphBuilder/instanceNormalization(input, options)/input}} tensor with {{MLInputOperandLayout/"nchw"}} layout, the [=list/size=] is equal to {{MLGraphBuilder/instanceNormalization(input, options)/input}}'s [=MLOperand/shape=][1].
 
     : bias
     ::
-        The 1-D tensor of the bias values whose [=list/size=] is equal to the size of the feature dimension of the input. For example, for an *input* tensor with {{MLInputOperandLayout/"nchw"}} layout, the [=list/size=] is equal to *input*'s [=MLOperand/shape=][1].
+        The 1-D tensor of the bias values whose [=list/size=] is equal to the size of the feature dimension of the input. For example, for an {{MLGraphBuilder/instanceNormalization(input, options)/input}} tensor with {{MLInputOperandLayout/"nchw"}} layout, the [=list/size=] is equal to {{MLGraphBuilder/instanceNormalization(input, options)/input}}'s [=MLOperand/shape=][1].
 
     : epsilon
     ::
@@ -4837,7 +4837,7 @@ partial dictionary MLOpSupportLimits {
         - input: an {{MLOperand}}. The input 4-D tensor.
         - options: an optional {{MLInstanceNormalizationOptions}}. The optional parameters of the operation.
 
-    **Returns:** an {{MLOperand}}. The instance-normalized 4-D tensor of the same shape as *input*.
+    **Returns:** an {{MLOperand}}. The instance-normalized 4-D tensor of the same shape as {{MLGraphBuilder/instanceNormalization(input, options)/input}}.
 
 
 

@@ -4990,7 +4990,7 @@ partial dictionary MLOpSupportLimits {
         - input: an {{MLOperand}}. The input N-D tensor.
         - options: an optional {{MLLayerNormalizationOptions}}. The optional parameters of the operation.
 
-    **Returns:** an {{MLOperand}}. The layer-normalized N-D tensor of the same shape as *input*.
+    **Returns:** an {{MLOperand}}. The layer-normalized N-D tensor of the same shape as {{MLGraphBuilder/layerNormalization(input, options)/input}}.
 

 
 

@@ -5125,7 +5125,7 @@ partial dictionary MLOpSupportLimits {
         - options: an optional {{MLLeakyReluOptions}}. The optional parameters of the operation.
 
     **Returns:**
-        - an {{MLOperand}}. The output tensor of the same shape as *input*.
+        - an {{MLOperand}}. The output tensor of the same shape as {{MLGraphBuilder/leakyRelu(input, options)/input}}.
 

 
 

@@ -5223,7 +5223,7 @@ partial dictionary MLOpSupportLimits {
         - options: an optional {{MLLinearOptions}}. The optional parameters of the operation.
 
     **Returns:**
-        - an {{MLOperand}}. The output tensor of the same shape as *input*.
+        - an {{MLOperand}}. The output tensor of the same shape as {{MLGraphBuilder/linear(input, options)/input}}.
 

 
 

@@ -6034,9 +6034,9 @@ partial dictionary MLOpSupportLimits {
 

     Computes the matrix product of two input tensors as follows:
-        - If both *a* and *b* are 2-dimensional, they are multiplied like conventional
+        - If both {{MLGraphBuilder/matmul(a, b, options)/a}} and {{MLGraphBuilder/matmul(a, b, options)/b}} are 2-dimensional, they are multiplied like conventional
             matrices and produce a 2-dimensional tensor as the output.
-        - If either *a* or *b* is `N`-dimensional where `N > 2`, it is treated as a stack of matrices with dimensions corresponding to the last two indices. The matrix multiplication will be [=broadcast=] according to [[!numpy-broadcasting-rule]]. The shapes of *a* and *b*, except the last two dimensions, must be [=bidirectionally broadcastable=]. The output is a `N`-dimensional tensor whose rank is the maximum [=MLOperand/rank=] of the input tensors. For each dimension, except the last two, of the output tensor, its size is the maximum size along that dimension of the input tensors.
+        - If either {{MLGraphBuilder/matmul(a, b, options)/a}} or {{MLGraphBuilder/matmul(a, b, options)/b}} is `N`-dimensional where `N > 2`, it is treated as a stack of matrices with dimensions corresponding to the last two indices. The matrix multiplication will be [=broadcast=] according to [[!numpy-broadcasting-rule]]. The shapes of {{MLGraphBuilder/matmul(a, b, options)/a}} and {{MLGraphBuilder/matmul(a, b, options)/b}}, except the last two dimensions, must be [=bidirectionally broadcastable=]. The output is a `N`-dimensional tensor whose rank is the maximum [=MLOperand/rank=] of the input tensors. For each dimension, except the last two, of the output tensor, its size is the maximum size along that dimension of the input tensors.
 

 
 
 

@@ -6152,8 +6152,8 @@ partial dictionary MLOpSupportLimits {
 

     **Arguments:**
         - input: an {{MLOperand}}. The input tensor.
-        - beginningPadding: [=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.
-        - endingPadding: [=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.
+        - beginningPadding: [=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 {{MLGraphBuilder/pad(input, beginningPadding, endingPadding, options)/input}}, {{MLGraphBuilder/pad(input, beginningPadding, endingPadding, options)/beginningPadding}}[*d*] indicates how many values to add before the content in that dimension.
+        - endingPadding: [=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 {{MLGraphBuilder/pad(input, beginningPadding, endingPadding, options)/input}}, {{MLGraphBuilder/pad(input, beginningPadding, endingPadding, options)/endingPadding}}[*d*] indicates how many values to add after the content in that dimension.
         - options: an optional {{MLPadOptions}}. The optional parameters of the operation.
 
     **Returns:** an {{MLOperand}}. The padded output tensor. Each dimension of the output tensor can be calculated as follows:
@@ -6530,11 +6530,11 @@ partial dictionary MLOpSupportLimits {
 

     **Arguments:**
         - input: an {{MLOperand}}. The input tensor.
-        - slope: an {{MLOperand}}. The slope tensor. Its shape must be [=bidirectionally broadcastable=] to the shape of *input*.
+        - slope: an {{MLOperand}}. The slope tensor. Its shape must be [=bidirectionally broadcastable=] to the shape of {{MLGraphBuilder/prelu(input, slope, options)/input}}.
         - options: an {{MLOperatorOptions}}. Specifies the optional parameters of the operation.
 
     **Returns:**
-        - an {{MLOperand}}. The output tensor of the same shape as *input*.
+        - an {{MLOperand}}. The output tensor of the same shape as {{MLGraphBuilder/prelu(input, slope, options)/input}}.
 

 
 

@@ -6889,7 +6889,7 @@ partial dictionary MLOpSupportLimits {
         - options: an {{MLOperatorOptions}}. Specifies the optional parameters of the operation.
 
     **Returns:**
-        - an {{MLOperand}}. The output tensor of the same shape as *input*.
+        - an {{MLOperand}}. The output tensor of the same shape as {{MLGraphBuilder/relu(input, options)/input}}.
 

 
 

@@ -7092,13 +7092,13 @@ partial dictionary MLOpSupportLimits {
     **Arguments:**
         - input: an {{MLOperand}}. The input tensor.
         - newShape: [=sequence=]<{{unsigned long}}>. The shape of the output tensor.
-            The number of elements implied by *newShape* must be the same as the
+            The number of elements implied by {{MLGraphBuilder/reshape(input, newShape, options)/newShape}} must be the same as the
             number of elements in the input tensor.
         - options: an {{MLOperatorOptions}}. Specifies the optional parameters of the operation.
 
     **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 *newShape*.
+    tensor is specified by {{MLGraphBuilder/reshape(input, newShape, options)/newShape}}.
 

 
 

@@ -7169,7 +7169,7 @@ partial dictionary MLOpSupportLimits {
         - options: an {{MLOperatorOptions}}. Specifies the optional parameters of the operation.
 
     **Returns:**
-        - an {{MLOperand}}. The output tensor of the same shape as *input*.
+        - an {{MLOperand}}. The output tensor of the same shape as {{MLGraphBuilder/sigmoid(input, options)/input}}.
 

 
 

@@ -7248,8 +7248,8 @@ partial  dictionary MLOpSupportLimits {
 

     **Arguments:**
         - input: an {{MLOperand}}. The input tensor.
-        - starts: [=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.
-        - sizes: [=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.
+        - starts: [=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 {{MLGraphBuilder/slice(input, starts, sizes, options)/input}}, {{MLGraphBuilder/slice(input, starts, sizes, options)/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.
+        - sizes: a [=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 {{MLGraphBuilder/slice(input, starts, sizes, options)/input}}, {{MLGraphBuilder/slice(input, starts, sizes, options)/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.
         - options: an {{MLOperatorOptions}}. Specifies the optional parameters of the operation.
 
     **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.
@@ -7328,7 +7328,7 @@ partial dictionary MLOpSupportLimits {
         - options: an {{MLOperatorOptions}}. Specifies the optional parameters of the operation.
 
     **Returns:**
-        - an {{MLOperand}}. The output N-D tensor that contains the softmax results, of the same shape as *input*.
+        - an {{MLOperand}}. The output N-D tensor that contains the softmax results, of the same shape as {{MLGraphBuilder/softmax(input, axis, options)/input}}.
 

 
 

@@ -7416,7 +7416,7 @@ partial dictionary MLOpSupportLimits {
         - options: an {{MLOperatorOptions}}. Specifies the optional parameters of the operation.
 
     **Returns:**
-        - an {{MLOperand}}. The output tensor of the same shape as *input*.
+        - an {{MLOperand}}. The output tensor of the same shape as {{MLGraphBuilder/softplus(input, options)/input}}.
 

 
 

@@ -7509,7 +7509,7 @@ partial dictionary MLOpSupportLimits {
         - options: an {{MLOperatorOptions}}. Specifies the optional parameters of the operation.
 
     **Returns:**
-        - an {{MLOperand}}. The output tensor of the same shape as *input*.
+        - an {{MLOperand}}. The output tensor of the same shape as {{MLGraphBuilder/softsign(input, options)/input}}.
 

 
 

@@ -7582,10 +7582,10 @@ partial dictionary MLOpSupportLimits {
 

     **Arguments:**
         - input: an {{MLOperand}}. The input tensor.
-        - splits: 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 {{MLSplitOptions/axis}}. If a [=sequence=]<{{unsigned long}}>, it specifies the sizes of each output tensor along the {{MLSplitOptions/axis}}. The sum of sizes must equal to the dimension size of *input* along {{MLSplitOptions/axis}}.
+        - splits: 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 {{MLGraphBuilder/split(input, splits, options)/input}} along {{MLSplitOptions/axis}}. If a [=sequence=]<{{unsigned long}}>, it specifies the sizes of each output tensor along the {{MLSplitOptions/axis}}. The sum of sizes must equal to the dimension size of {{MLGraphBuilder/split(input, splits, options)/input}} along {{MLSplitOptions/axis}}.
         - options: an optional {{MLSplitOptions}}. The optional parameters of the operation.
 
-    **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*].
+    **Returns:** [=sequence=]<{{MLOperand}}>. The split output tensors. If {{MLGraphBuilder/split(input, splits, options)/splits}} is an {{unsigned long}}, the [=list/size=] of the output is equal to {{MLGraphBuilder/split(input, splits, options)/splits}}. The shape of each output tensor is the same as {{MLGraphBuilder/split(input, splits, options)/input}} except the dimension size of {{MLSplitOptions/axis}} equals to the quotient of dividing the dimension size of {{MLGraphBuilder/split(input, splits, options)/input}} along {{MLSplitOptions/axis}} by {{MLGraphBuilder/split(input, splits, options)/splits}}. If {{MLGraphBuilder/split(input, splits, options)/splits}} is a [=sequence=]<{{unsigned long}}>, the [=list/size=] of the output equals the [=list/size=] of {{MLGraphBuilder/split(input, splits, options)/splits}}. The shape of the *i*-th output tensor is the same as {{MLGraphBuilder/split(input, splits, options)/input}} except along {{MLSplitOptions/axis}} where the dimension size is {{MLGraphBuilder/split(input, splits, options)/splits}}[*i*].
 

 
 {{MLSplitOptions}} has the following members:
@@ -7707,7 +7707,7 @@ partial dictionary MLOpSupportLimits {
         - options: an {{MLOperatorOptions}}. Specifies the optional parameters of the operation.
 
     **Returns:**
-        - an {{MLOperand}}. The output tensor of the same shape as *input*.
+        - an {{MLOperand}}. The output tensor of the same shape as {{MLGraphBuilder/tanh(input, options)/input}}.