fix(generators): Improve consistency of migrated language generators (#7662)

cpcallen · web-flow · commit b198e2f4ae57 · 2023-11-28T16:57:31.000Z
* docs(generators): @fileoverview -> @file; delete @Suppress * fix(generators): Fix return type of getAdjusted And improve its documentation too. Fix the @returns doc for PythonGenerator's getAdjustedInt but (for now) don't change the type because it does actually return numbers in some circumstances.
diff --git a/generators/dart.ts b/generators/dart.ts
@@ -5,9 +5,9 @@
  */
 
 /**
- * @fileoverview Complete helper functions for generating Dart for
- *     blocks.  This is the entrypoint for dart_compressed.js.
- * @suppress {extraRequire}
+ * @file Instantiate a DartGenerator and populate it with the complete
+ * set of block generator functions for Dart.  This is the entrypoint
+ * for dart_compressed.js.
  */
 
 // Former goog.module ID: Blockly.Dart.all
diff --git a/generators/dart/colour.ts b/generators/dart/colour.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Dart for colour blocks.
+ * @file Generating Dart for colour blocks.
  */
 
 // Former goog.module ID: Blockly.Dart.colour
diff --git a/generators/dart/dart_generator.ts b/generators/dart/dart_generator.ts
@@ -269,15 +269,15 @@ export class DartGenerator extends CodeGenerator {
    * @param delta Value to add.
    * @param negate Whether to negate the value.
    * @param order The highest order acting on this value.
-   * @returns The adjusted value.
+   * @returns The adjusted value or code that evaluates to it.
    */
   getAdjusted(
     block: Block,
     atId: string,
     delta = 0,
     negate = false,
     order = Order.NONE,
-  ): string | number {
+  ): string {
     if (block.workspace.options.oneBasedIndex) {
       delta--;
     }
diff --git a/generators/dart/lists.ts b/generators/dart/lists.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Dart for list blocks.
+ * @file Generating Dart for list blocks.
  */
 
 // Former goog.module ID: Blockly.Dart.lists
diff --git a/generators/dart/logic.ts b/generators/dart/logic.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Dart for logic blocks.
+ * @file Generating Dart for logic blocks.
  */
 
 // Former goog.module ID: Blockly.Dart.logic
diff --git a/generators/dart/loops.ts b/generators/dart/loops.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Dart for loop blocks.
+ * @file Generating Dart for loop blocks.
  */
 
 // Former goog.module ID: Blockly.Dart.loops
diff --git a/generators/dart/math.ts b/generators/dart/math.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Dart for math blocks.
+ * @file Generating Dart for math blocks.
  */
 
 // Former goog.module ID: Blockly.Dart.math
diff --git a/generators/dart/procedures.ts b/generators/dart/procedures.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Dart for procedure blocks.
+ * @file Generating Dart for procedure blocks.
  */
 
 // Former goog.module ID: Blockly.Dart.procedures
diff --git a/generators/dart/text.ts b/generators/dart/text.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Dart for text blocks.
+ * @file Generating Dart for text blocks.
  */
 
 // Former goog.module ID: Blockly.Dart.texts
diff --git a/generators/dart/variables.ts b/generators/dart/variables.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Dart for variable blocks.
+ * @file Generating Dart for variable blocks.
  */
 
 // Former goog.module ID: Blockly.Dart.variables
diff --git a/generators/dart/variables_dynamic.ts b/generators/dart/variables_dynamic.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Dart for dynamic variable blocks.
+ * @file Generating Dart for dynamic variable blocks.
  */
 
 // Former goog.module ID: Blockly.Dart.variablesDynamic
diff --git a/generators/javascript.ts b/generators/javascript.ts
@@ -5,9 +5,9 @@
  */
 
 /**
- * @fileoverview Complete helper functions for generating JavaScript for
- *     blocks.  This is the entrypoint for javascript_compressed.js.
- * @suppress {extraRequire}
+ * @file Instantiate a JavascriptGenerator and populate it with the
+ * complete set of block generator functions for JavaScript.  This is
+ * the entrypoint for javascript_compressed.js.
  */
 
 // Former goog.module ID: Blockly.JavaScript.all
diff --git a/generators/javascript/colour.ts b/generators/javascript/colour.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating JavaScript for colour blocks.
+ * @file Generating JavaScript for colour blocks.
  */
 
 // Former goog.module ID: Blockly.JavaScript.colour
diff --git a/generators/javascript/javascript_generator.ts b/generators/javascript/javascript_generator.ts
@@ -295,15 +295,15 @@ export class JavascriptGenerator extends CodeGenerator {
    * @param delta Value to add.
    * @param negate Whether to negate the value.
    * @param order The highest order acting on this value.
-   * @returns The adjusted value.
+   * @returns The adjusted value or code that evaluates to it.
    */
   getAdjusted(
     block: Block,
     atId: string,
     delta = 0,
     negate = false,
     order = Order.NONE,
-  ): string | number {
+  ): string {
     if (block.workspace.options.oneBasedIndex) {
       delta--;
     }
diff --git a/generators/javascript/lists.ts b/generators/javascript/lists.ts
@@ -5,8 +5,7 @@
  */
 
 /**
- * @fileoverview Generating JavaScript for list blocks.
- * @suppress {missingRequire}
+ * @file Generating JavaScript for list blocks.
  */
 
 // Former goog.module ID: Blockly.JavaScript.lists
diff --git a/generators/javascript/logic.ts b/generators/javascript/logic.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating JavaScript for logic blocks.
+ * @file Generating JavaScript for logic blocks.
  */
 
 // Former goog.module ID: Blockly.JavaScript.logic
diff --git a/generators/javascript/loops.ts b/generators/javascript/loops.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating JavaScript for loop blocks.
+ * @file Generating JavaScript for loop blocks.
  */
 
 // Former goog.module ID: Blockly.JavaScript.loops
diff --git a/generators/javascript/math.ts b/generators/javascript/math.ts
@@ -5,8 +5,7 @@
  */
 
 /**
- * @fileoverview Generating JavaScript for math blocks.
- * @suppress {missingRequire}
+ * @file Generating JavaScript for math blocks.
  */
 
 // Former goog.module ID: Blockly.JavaScript.math
diff --git a/generators/javascript/procedures.ts b/generators/javascript/procedures.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating JavaScript for procedure blocks.
+ * @file Generating JavaScript for procedure blocks.
  */
 
 // Former goog.module ID: Blockly.JavaScript.procedures
diff --git a/generators/javascript/text.ts b/generators/javascript/text.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating JavaScript for text blocks.
+ * @file Generating JavaScript for text blocks.
  */
 
 // Former goog.module ID: Blockly.JavaScript.texts
diff --git a/generators/javascript/variables.ts b/generators/javascript/variables.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating JavaScript for variable blocks.
+ * @file Generating JavaScript for variable blocks.
  */
 
 // Former goog.module ID: Blockly.JavaScript.variables
diff --git a/generators/javascript/variables_dynamic.ts b/generators/javascript/variables_dynamic.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating JavaScript for dynamic variable blocks.
+ * @file Generating JavaScript for dynamic variable blocks.
  */
 
 // Former goog.module ID: Blockly.JavaScript.variablesDynamic
diff --git a/generators/python.ts b/generators/python.ts
@@ -5,9 +5,9 @@
  */
 
 /**
- * @fileoverview Complete helper functions for generating Python for
- *     blocks.  This is the entrypoint for python_compressed.js.
- * @suppress {extraRequire}
+ * @file Instantiate a PythonGenerator and populate it with the
+ * complete set of block generator functions for Python.  This is the
+ * entrypoint for python_compressed.js.
  */
 
 // Former goog.module ID: Blockly.Python.all
diff --git a/generators/python/colour.ts b/generators/python/colour.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Python for colour blocks.
+ * @file Generating Python for colour blocks.
  */
 
 // Former goog.module ID: Blockly.Python.colour
diff --git a/generators/python/lists.ts b/generators/python/lists.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Python for list blocks.
+ * @file Generating Python for list blocks.
  */
 
 // Former goog.module ID: Blockly.Python.lists
diff --git a/generators/python/logic.ts b/generators/python/logic.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Python for logic blocks.
+ * @file Generating Python for logic blocks.
  */
 
 // Former goog.module ID: Blockly.Python.logic
diff --git a/generators/python/loops.ts b/generators/python/loops.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Python for loop blocks.
+ * @file Generating Python for loop blocks.
  */
 
 // Former goog.module ID: Blockly.Python.loops
diff --git a/generators/python/math.ts b/generators/python/math.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Python for math blocks.
+ * @file Generating Python for math blocks.
  */
 
 // Former goog.module ID: Blockly.Python.math
diff --git a/generators/python/procedures.ts b/generators/python/procedures.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Python for procedure blocks.
+ * @file Generating Python for procedure blocks.
  */
 
 // Former goog.module ID: Blockly.Python.procedures
diff --git a/generators/python/python_generator.ts b/generators/python/python_generator.ts
@@ -318,7 +318,7 @@ export class PythonGenerator extends CodeGenerator {
    * @param atId The ID of the input block to get (and adjust) the value of.
    * @param delta Value to add.
    * @param negate Whether to negate the value.
-   * @returns The adjusted value.
+   * @returns The adjusted value or code that evaluates to it.
    */
   getAdjustedInt(
     block: Block,
diff --git a/generators/python/text.ts b/generators/python/text.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Python for text blocks.
+ * @file Generating Python for text blocks.
  */
 
 // Former goog.module ID: Blockly.Python.texts
diff --git a/generators/python/variables.ts b/generators/python/variables.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Python for variable blocks.
+ * @file Generating Python for variable blocks.
  */
 
 // Former goog.module ID: Blockly.Python.variables
diff --git a/generators/python/variables_dynamic.ts b/generators/python/variables_dynamic.ts
@@ -5,7 +5,7 @@
  */
 
 /**
- * @fileoverview Generating Python for dynamic variable blocks.
+ * @file Generating Python for dynamic variable blocks.
  */
 
 // Former goog.module ID: Blockly.Python.variablesDynamic
