From b198e2f4ae5755ac53e79ed85e246976080137b6 Mon Sep 17 00:00:00 2001
From: Christopher Allen <cpcallen+git@google.com>
Date: Tue, 28 Nov 2023 16:57:31 +0000
Subject: [PATCH] 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                            | 6 +++---
 generators/dart/colour.ts                     | 2 +-
 generators/dart/dart_generator.ts             | 4 ++--
 generators/dart/lists.ts                      | 2 +-
 generators/dart/logic.ts                      | 2 +-
 generators/dart/loops.ts                      | 2 +-
 generators/dart/math.ts                       | 2 +-
 generators/dart/procedures.ts                 | 2 +-
 generators/dart/text.ts                       | 2 +-
 generators/dart/variables.ts                  | 2 +-
 generators/dart/variables_dynamic.ts          | 2 +-
 generators/javascript.ts                      | 6 +++---
 generators/javascript/colour.ts               | 2 +-
 generators/javascript/javascript_generator.ts | 4 ++--
 generators/javascript/lists.ts                | 3 +--
 generators/javascript/logic.ts                | 2 +-
 generators/javascript/loops.ts                | 2 +-
 generators/javascript/math.ts                 | 3 +--
 generators/javascript/procedures.ts           | 2 +-
 generators/javascript/text.ts                 | 2 +-
 generators/javascript/variables.ts            | 2 +-
 generators/javascript/variables_dynamic.ts    | 2 +-
 generators/python.ts                          | 6 +++---
 generators/python/colour.ts                   | 2 +-
 generators/python/lists.ts                    | 2 +-
 generators/python/logic.ts                    | 2 +-
 generators/python/loops.ts                    | 2 +-
 generators/python/math.ts                     | 2 +-
 generators/python/procedures.ts               | 2 +-
 generators/python/python_generator.ts         | 2 +-
 generators/python/text.ts                     | 2 +-
 generators/python/variables.ts                | 2 +-
 generators/python/variables_dynamic.ts        | 2 +-
 33 files changed, 41 insertions(+), 43 deletions(-)

diff --git a/generators/dart.ts b/generators/dart.ts
index 3bd1271ad..ee21b1fbd 100644
--- 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
index b55fc5e6f..ac72fc04c 100644
--- 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
index b2eb80cdd..222bbd41d 100644
--- a/generators/dart/dart_generator.ts
+++ b/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--;
     }
diff --git a/generators/dart/lists.ts b/generators/dart/lists.ts
index d1b65cc53..4aaf39905 100644
--- 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
index 82d9d563b..45c385b86 100644
--- 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
index 5f54d2018..a6b6bb180 100644
--- 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
index 01830a0b1..550821e9f 100644
--- 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
index 934e52318..5102432ad 100644
--- 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
index e8c9be637..108516019 100644
--- 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
index 1910befc9..4863d0417 100644
--- 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
index 6a92fff91..68cdf22d6 100644
--- 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
index 079c2f793..2358d187d 100644
--- 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
index 3e7089cd7..b599e76d9 100644
--- 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
index 547b7daf7..98c6a4a4b 100644
--- a/generators/javascript/javascript_generator.ts
+++ b/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--;
     }
diff --git a/generators/javascript/lists.ts b/generators/javascript/lists.ts
index 0a1fcc87f..839d959cb 100644
--- 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
index bdc51f997..60174c85a 100644
--- 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
index a5dd86357..555e43ff1 100644
--- 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
index c05e817cf..e8ab2852f 100644
--- 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
index f0b5c94f0..a835271e7 100644
--- 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
index 7e3b0e4c1..1681979ec 100644
--- 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
index 88320be54..33a4f7d31 100644
--- 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
index b88d03fc1..27cd214e4 100644
--- 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
index e2345a776..08ab10e81 100644
--- 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
index 82f9dd37b..729d87cf5 100644
--- 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
index 7577cc417..6e412c23f 100644
--- 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
index e562c6794..40133600d 100644
--- 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
index 1d2d3a86e..7ca7a5582 100644
--- 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
index d458b0e87..59b68c7a7 100644
--- 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
index ad45f2dfb..0d9b2e85d 100644
--- 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
index 5e5daf9f2..33c07fe39 100644
--- 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
index 7b554efda..5d93e91ed 100644
--- 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
index 5510e5e0f..a323181f1 100644
--- 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
index 4ca397258..884700160 100644
--- 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