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

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

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

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

generators/dart/dart_generator.ts

@@ -269,7 +269,7 @@ 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,
@@ -277,7 +277,7 @@ export class DartGenerator extends CodeGenerator {
     delta = 0,
     negate = false,
     order = Order.NONE,
-  ): string | number {
+  ): string {
     if (block.workspace.options.oneBasedIndex) {
       delta--;
     }

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

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

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

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

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

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

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

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

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

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

generators/javascript/javascript_generator.ts

@@ -295,7 +295,7 @@ 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,
@@ -303,7 +303,7 @@ export class JavascriptGenerator extends CodeGenerator {
     delta = 0,
     negate = false,
     order = Order.NONE,
-  ): string | number {
+  ): string {
     if (block.workspace.options.oneBasedIndex) {
       delta--;
     }

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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,

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

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

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