Style: Ensure algorithm steps end in '.' or ':'

Add lint rule, fix a handful of exceptions.
webmachinelearning · Jun 12, 2024 · c337d90 · c337d90
1 parent 74b9831
commit c337d90
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 10 deletions.
diff --git a/index.bs b/index.bs
@@ -750,11 +750,11 @@ The <dfn dfn-for=MLContextOptions dfn-type=dict-member>powerPreference</dfn> opt
     To <dfn>create a context</dfn> given [=realm=] |realm| and |options| (a {{GPUDevice}} or {{MLContextOptions}}), run these steps:
 </summary>
     1. Let |context| be a new {{MLContext}} object with |realm|.
-    1. If |options| is a {{GPUDevice}} object,
+    1. If |options| is a {{GPUDevice}} object:
         1. Set |context|.{{MLContext/[[contextType]]}} to "[=context type/webgpu=]".
         1. Set |context|.{{MLContext/[[deviceType]]}} to {{MLDeviceType/"gpu"}}.
         1. Set |context|.{{MLContext/[[powerPreference]]}} to {{MLPowerPreference/"default"}}.
-    1. Otherwise,
+    1. Otherwise:
         1. Set |context|.{{MLContext/[[contextType]]}} to "[=context type/default=]".
         1. If |options|["{{MLContextOptions/deviceType}}"] [=map/exists=], then set |context|.{{MLContext/[[deviceType]]}} to |options|["{{MLContextOptions/deviceType}}"]. Otherwise, set |context|.{{MLContext/[[deviceType]]}} to {{MLDeviceType/"cpu"}}.
         1. If |options|["{{MLContextOptions/powerPreference}}"] [=map/exists=], then set |context|.{{MLContext/[[powerPreference]]}} to |options|["{{MLContextOptions/powerPreference}}"]. Otherwise, set |context|.{{MLContext/[[powerPreference]]}} to {{MLPowerPreference/"default"}}.
@@ -2106,7 +2106,7 @@ partial interface MLGraphBuilder {
                     1. Let |filterInputChannels| be |filterShape|[3].
             </dl>
         1. If |inputChannels| is not equal to |filterInputChannels|, then [=exception/throw=] a {{TypeError}}.
-        1. Let |outputChannels| be |filterOutputChannels| * |options|.{{MLConvTranspose2dOptions/groups}}
+        1. Let |outputChannels| be |filterOutputChannels| * |options|.{{MLConvTranspose2dOptions/groups}}.
         1. If |options|.{{MLConvTranspose2dOptions/bias}} [=map/exists=]:
             1. If its [=MLOperand/shape=] is not equal to « |outputChannels| », then [=exception/throw=] a {{TypeError}}.
             1. If its [=MLOperand/dataType=] is not equal to |input|'s [=MLOperand/dataType=], then [=exception/throw=] a {{TypeError}}.
@@ -3234,8 +3234,8 @@ partial interface MLGraphBuilder {
     1. If |options|.{{MLGruCellOptions/activations}} [=map/exists=], and [=MLGraphBuilder/validating activation=] with [=this=] and any [=list/item=] in it returns false, then [=exception/throw=] a {{TypeError}}.
     1. If |input|'s [=MLOperand/dataType=] is not {{MLOperandDataType/"float32"}} or {{MLOperandDataType/"float16"}}, then [=exception/throw=] a {{TypeError}}.
     1. If |input|'s [=MLOperand/rank=] is not 2, then [=exception/throw=] a {{TypeError}}.
-    1. Let |batchSize| be |input|'s [=MLOperand/shape=][0];
-    1. Let |inputSize| be |input|'s [=MLOperand/shape=][1];
+    1. Let |batchSize| be |input|'s [=MLOperand/shape=][0].
+    1. Let |inputSize| be |input|'s [=MLOperand/shape=][1].
     1. If the [=MLOperand/dataType=] of any of |weight|, |recurrentWeight|, or |hiddenState| is not equal to |input|'s [=MLOperand/dataType=], then [=exception/throw=] a {{TypeError}}.
     1. If |weight|'s [=MLOperand/shape=] is not equal to « 3 * |hiddenSize|, |inputSize| », then [=exception/throw=] a {{TypeError}}.
     1. If |recurrentWeight|'s [=MLOperand/shape=] is not equal to « 3 * |hiddenSize|, |hiddenSize| », then [=exception/throw=] a {{TypeError}}.
@@ -4410,9 +4410,9 @@ partial interface MLGraphBuilder {
   <summary>
     To <dfn dfn-for=MLGraphBuilder>calculate matmul output sizes</dfn>, given {{MLOperand}} |a| and {{MLOperand}} |b| run the following steps:
   </summary>
-    1. Let |shapeA| be a [=list/clone=] of |a|'s [=MLOperand/shape=]
+    1. Let |shapeA| be a [=list/clone=] of |a|'s [=MLOperand/shape=].
     1. Let |rankA| be |a|'s [=MLOperand/rank=].
-    1. Let |shapeB| be a [=list/clone=] of |b|'s [=MLOperand/shape=]
+    1. Let |shapeB| be a [=list/clone=] of |b|'s [=MLOperand/shape=].
     1. Let |rankB| be |b|'s [=MLOperand/rank=].
     1. If either |rankA| or |rankB| is less than 2, then [=exception/throw=] a {{TypeError}}.
     1. Let |colsA| be |shapeA|[|rankA| - 1].
@@ -4509,7 +4509,7 @@ partial interface MLGraphBuilder {
     The <dfn method for=MLGraphBuilder>pad(|input|, |beginningPadding|, |endingPadding|, |options|)</dfn> method steps are:
   </summary>
     1. If [=MLGraphBuilder/validating operand=] with [=this=] and |input| returns false, then [=exception/throw=] a {{TypeError}}.
-    1. If |input|'s [=MLOperand/rank=] is 0, then [=exception/throw=] a {{TypeError}}
+    1. If |input|'s [=MLOperand/rank=] is 0, then [=exception/throw=] a {{TypeError}}.
     1. If |beginningPadding|'s [=list/size=] and |endingPadding|'s [=list/size=] are not both equal to |input|'s [=MLOperand/rank=], then [=exception/throw=] a {{TypeError}}.
     1. Let |desc| be a copy of |input|.{{MLOperand/[[descriptor]]}}.
     1. Let |outputShape| be the result of [=MLGraphBuilder/calculating padding output sizes=] given |input|, |beginningPadding| and |endingPadding|.
@@ -4692,7 +4692,7 @@ partial interface MLGraphBuilder {
         1. Let |outputSizes| be the result of [=MLGraphBuilder/calculating conv2d output sizes=] given |inputHeight|, |inputWidth|, |windowDimensions|[0], |windowDimensions|[1], |padding|, |strides|, and |dilations|.
         1. Let |outputHeight| be |outputSizes|[0].
         1. Let |outputWidth| be |outputSizes|[1].
-        1. Switch on |roundingType|
+        1. Switch on |roundingType|:
             <dl class=switch>
                 : {{MLRoundingType/"floor"}}
                 ::
@@ -4965,7 +4965,7 @@ partial interface MLGraphBuilder {
 
     <div algorithm>
     The <dfn method for=MLGraphBuilder>reduceMean(|input|, |options|)</dfn> method steps are:
-        1. Let |output| be the result of running the [=MLGraphBuilder/reduce-op | create reduce operation=] given "reduceMean", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}} »
+        1. Let |output| be the result of running the [=MLGraphBuilder/reduce-op | create reduce operation=] given "reduceMean", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}} ».
             1. If that [=exception/throws=] an error, then re-[=exception/throw=] the error.
         1. Return |output|.
     </div>

diff --git a/tools/lint.mjs b/tools/lint.mjs
@@ -257,4 +257,20 @@ for (const pre of root.querySelectorAll('pre.highlight:not(.idl)')) {
   }
 }
 
+// Ensure algorithm steps end in '.' or ':'.
+for (const match of source.matchAll(/^ *\d+\. .*$/mg)) {
+  let str = match[0].trim();
+
+  // Strip asterisks from things like "1. *Make graph connections.*"
+  const match2 = str.match(/^(\d+\. )\*(.*)\*$/);
+  if (match2) {
+    str = match2[1] + match2[2];
+  }
+
+  const match3 = str.match(/[^.:]$/);
+  if (match3) {
+    error(`Algorithm steps should end with '.' or ':': ${format(match3)}`);
+  }
+}
+
 globalThis.process.exit(exitCode);