fix: return annotations (#7118)

* chore: remove suppress annotations

* chore: remove fileoverview annotation

* chore: remove other unused annotations

* chore: change return to returns

* chore: enable tag linting

.eslintrc.js

@@ -121,9 +121,18 @@ function buildTSOverride({files, tsconfig}) {
           'publicOnly': true,
         },
       ],
-      // Disable because of false alarms with Closure-supported tags.
-      // Re-enable after Closure is removed.
-      'jsdoc/check-tag-names': ['off'],
+      'jsdoc/check-tag-names': [
+        'error',
+        {
+          'definedTags': [
+            'sealed',
+            'typeParam',
+            'remarks',
+            'define',
+            'nocollapse',
+          ],
+        },
+      ],
       // Re-enable after Closure is removed. There shouldn't even be
       // types in the TsDoc.
       // These are "types" because of Closure's @suppress {warningName}

blocks/colour.ts

@@ -4,10 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * @fileoverview Colour blocks for Blockly.
- */
-
 import * as goog from '../closure/goog/goog.js';
 goog.declareModuleId('Blockly.libraryBlocks.colour');
 

blocks/lists.ts

@@ -4,11 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * @fileoverview List blocks for Blockly.
- * @suppress {checkTypes}
- */
-
 import * as goog from '../closure/goog/goog.js';
 goog.declareModuleId('Blockly.libraryBlocks.lists');
 
@@ -163,7 +158,7 @@ const LISTS_CREATE_WITH = {
   /**
    * Returns the state of this block as a JSON serializable object.
    *
-   * @return The state of this block, ie the item count.
+   * @returns The state of this block, ie the item count.
    */
   saveExtraState: function (this: CreateWithBlock): {itemCount: number} {
     return {
@@ -183,7 +178,7 @@ const LISTS_CREATE_WITH = {
    * Populate the mutator's dialog with this block's components.
    *
    * @param workspace Mutator's workspace.
-   * @return Root block in mutator.
+   * @returns Root block in mutator.
    */
   decompose: function (
     this: CreateWithBlock,
@@ -482,7 +477,7 @@ const LISTS_GETINDEX = {
    * Create XML to represent whether the block is a statement or a value.
    * Also represent whether there is an 'AT' input.
    *
-   * @return XML storage element.
+   * @returns XML storage element.
    */
   mutationToDom: function (this: GetIndexBlock): Element {
     const container = xmlUtils.createElement('mutation');
@@ -509,7 +504,7 @@ const LISTS_GETINDEX = {
    * Returns the state of this block as a JSON serializable object.
    * Returns null for efficiency if no state is needed (not a statement)
    *
-   * @return The state of this block, ie whether it's a statement.
+   * @returns The state of this block, ie whether it's a statement.
    */
   saveExtraState: function (this: GetIndexBlock): {
     isStatement: boolean;
@@ -586,7 +581,7 @@ const LISTS_GETINDEX = {
     menu.setValidator(
       /**
        * @param value The input value.
-       * @return Null if the field has been replaced; otherwise undefined.
+       * @returns Null if the field has been replaced; otherwise undefined.
        */
       function (this: FieldDropdown, value: string) {
         const newAt = value === 'FROM_START' || value === 'FROM_END';
@@ -699,7 +694,7 @@ const LISTS_SETINDEX = {
   /**
    * Create XML to represent whether there is an 'AT' input.
    *
-   * @return XML storage element.
+   * @returns XML storage element.
    */
   mutationToDom: function (this: SetIndexBlock): Element {
     const container = xmlUtils.createElement('mutation');
@@ -725,7 +720,7 @@ const LISTS_SETINDEX = {
    * encoded in the dropdown values, but must have an implementation to avoid
    * the backward compatible XML mutations being serialized.
    *
-   * @return The state of this block.
+   * @returns The state of this block.
    */
   saveExtraState: function (this: SetIndexBlock): null {
     return null;
@@ -765,7 +760,7 @@ const LISTS_SETINDEX = {
     menu.setValidator(
       /**
        * @param value The input value.
-       * @return Null if the field has been replaced; otherwise undefined.
+       * @returns Null if the field has been replaced; otherwise undefined.
        */
       function (this: FieldDropdown, value: string) {
         const newAt = value === 'FROM_START' || value === 'FROM_END';
@@ -834,7 +829,7 @@ const LISTS_GETSUBLIST = {
   /**
    * Create XML to represent whether there are 'AT' inputs.
    *
-   * @return XML storage element.
+   * @returns XML storage element.
    */
   mutationToDom: function (this: GetSublistBlock): Element {
     const container = xmlUtils.createElement('mutation');
@@ -862,7 +857,7 @@ const LISTS_GETSUBLIST = {
    * encoded in the dropdown values, but must have an implementation to avoid
    * the backward compatible XML mutations being serialized.
    *
-   * @return The state of this block.
+   * @returns The state of this block.
    */
   saveExtraState: function (this: GetSublistBlock): null {
     return null;
@@ -906,7 +901,7 @@ const LISTS_GETSUBLIST = {
     menu.setValidator(
       /**
        * @param value The input value.
-       * @return Null if the field has been replaced; otherwise undefined.
+       * @returns Null if the field has been replaced; otherwise undefined.
        */
       function (this: FieldDropdown, value: string) {
         const newAt = value === 'FROM_START' || value === 'FROM_END';
@@ -1047,7 +1042,7 @@ blocks['lists_split'] = {
   /**
    * Create XML to represent the input and output types.
    *
-   * @return XML storage element.
+   * @returns XML storage element.
    */
   mutationToDom: function (this: SplitBlock): Element {
     const container = xmlUtils.createElement('mutation');
@@ -1069,7 +1064,7 @@ blocks['lists_split'] = {
    * encoded in the dropdown values, but must have an implementation to avoid
    * the backward compatible XML mutations being serialized.
    *
-   * @return The state of this block.
+   * @returns The state of this block.
    */
   saveExtraState: function (this: SplitBlock): null {
     return null;

blocks/loops.ts

@@ -4,10 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * @fileoverview Loop blocks for Blockly.
- */
-
 import * as goog from '../closure/goog/goog.js';
 goog.declareModuleId('Blockly.libraryBlocks.loops');
 

blocks/math.ts

@@ -4,10 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * @fileoverview Math blocks for Blockly.
- */
-
 import * as goog from '../closure/goog/goog.js';
 goog.declareModuleId('Blockly.libraryBlocks.math');
 

blocks/text.ts

@@ -4,10 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * @fileoverview Text blocks for Blockly.
- */
-
 import * as goog from '../closure/goog/goog.js';
 goog.declareModuleId('Blockly.libraryBlocks.texts');
 
@@ -333,7 +329,7 @@ const GET_SUBSTRING_BLOCK = {
     menu.setValidator(
       /**
        * @param value The input value.
-       * @return Null if the field has been replaced; otherwise undefined.
+       * @returns Null if the field has been replaced; otherwise undefined.
        */
       function (this: FieldDropdown, value: any): null | undefined {
         const newAt = value === 'FROM_START' || value === 'FROM_END';

blocks/variables.ts

@@ -4,11 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * @fileoverview Variable blocks for Blockly.
- * @suppress {checkTypes}
- */
-
 import * as goog from '../closure/goog/goog.js';
 goog.declareModuleId('Blockly.libraryBlocks.variables');
 

blocks/variables_dynamic.ts

@@ -4,11 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * @fileoverview Variable blocks for Blockly.
- * @suppress {checkTypes}
- */
-
 import * as goog from '../closure/goog/goog.js';
 goog.declareModuleId('Blockly.libraryBlocks.variablesDynamic');
 

core/block.ts

@@ -312,7 +312,6 @@ export class Block implements IASTNodeLocation, IDeletable {
    * @param healStack If true, then try to heal any gap by connecting the next
    *     statement with the previous statement.  Otherwise, dispose of all
    *     children of this block.
-   * @suppress {checkTypes}
    */
   dispose(healStack: boolean) {
     if (this.isDeadOrDying()) return;
@@ -2246,7 +2245,7 @@ export class Block implements IASTNodeLocation, IDeletable {
    * block.
    *
    * @param type The type of the icon to remove from the block.
-   * @return True if an icon with the given type was found, false otherwise.
+   * @returns True if an icon with the given type was found, false otherwise.
    */
   removeIcon(type: string): boolean {
     if (!this.hasIcon(type)) return false;
@@ -2255,22 +2254,22 @@ export class Block implements IASTNodeLocation, IDeletable {
   }
 
   /**
-   * @return True if an icon with the given type exists on the block,
+   * @returns True if an icon with the given type exists on the block,
    *     false otherwise.
    */
   hasIcon(type: string): boolean {
     return this.icons.some((icon) => icon.getType() === type);
   }
 
   /**
-   * @return The icon with the given type if it exists on the block, undefined
+   * @returns The icon with the given type if it exists on the block, undefined
    *     otherwise.
    */
   getIcon(type: string): IIcon | undefined {
     return this.icons.find((icon) => icon.getType() === type);
   }
 
-  /** @return An array of the icons attached to this block. */
+  /** @returns An array of the icons attached to this block. */
   getIcons(): IIcon[] {
     return [...this.icons];
   }

core/block_svg.ts

@@ -779,7 +779,6 @@ export class BlockSvg
    *     statement with the previous statement.  Otherwise, dispose of all
    *     children of this block.
    * @param animate If true, show a disposal animation and sound.
-   * @suppress {checkTypes}
    */
   override dispose(healStack?: boolean, animate?: boolean) {
     if (this.isDeadOrDying()) return;

core/bubbles/bubble.ts

@@ -149,7 +149,7 @@ export abstract class Bubble implements IBubble {
     this.renderTail();
   }
 
-  /** @return the size of this bubble. */
+  /** @returns the size of this bubble. */
   protected getSize() {
     return this.size;
   }
@@ -417,7 +417,7 @@ export abstract class Bubble implements IBubble {
   }
 
   /**
-   * @return a rect defining the bounds of the workspace's view in workspace
+   * @returns a rect defining the bounds of the workspace's view in workspace
    * coordinates.
    */
   private getWorkspaceViewRect(viewMetrics: ContainerRegion): Rect {
@@ -436,7 +436,7 @@ export abstract class Bubble implements IBubble {
     return new Rect(top, bottom, left, right);
   }
 
-  /** @return the scrollbar thickness in workspace units. */
+  /** @returns the scrollbar thickness in workspace units. */
   private getScrollbarThickness() {
     return Scrollbar.scrollbarThickness / this.workspace.scale;
   }

core/bubbles/text_bubble.ts

@@ -26,7 +26,7 @@ export class TextBubble extends Bubble {
     this.updateBubbleSize();
   }
 
-  /** @return the current text of this text bubble. */
+  /** @returns the current text of this text bubble. */
   getText(): string {
     return this.text;
   }

core/contextmenu.ts

@@ -310,7 +310,6 @@ export function commentDuplicateOption(
  *     originated.
  * @param e The right-click mouse event.
  * @returns A menu option, containing text, enabled, and a callback.
- * @suppress {strictModuleDepCheck,checkTypes} Suppress checks while workspace
  *     comments are not bundled in.
  * @internal
  */

core/flyout_base.ts

@@ -423,8 +423,6 @@ export abstract class Flyout extends DeleteArea implements IFlyout {
   /**
    * Dispose of this flyout.
    * Unlink from all DOM elements to prevent memory leaks.
-   *
-   * @suppress {checkTypes}
    */
   dispose() {
     this.hide();

core/generator.ts

@@ -20,8 +20,6 @@ import type {Workspace} from './workspace.js';
 
 /**
  * Class for a code generator that translates the blocks into a language.
- *
- * @unrestricted
  */
 export class CodeGenerator {
   name_: string;

core/gesture.ts

@@ -1174,7 +1174,7 @@ export class Gesture {
     );
   }
 
-  /** @return Whether this gesture is a click on an icon. */
+  /** @returns Whether this gesture is a click on an icon. */
   private isIconClick(): boolean {
     return !!this.startIcon && !this.hasExceededDragRadius;
   }

core/inputs/input.ts

@@ -287,8 +287,6 @@ export class Input {
 
   /**
    * Sever all links to this input.
-   *
-   * @suppress {checkTypes}
    */
   dispose() {
     for (let i = 0, field; (field = this.fieldRow[i]); i++) {

core/interfaces/i_has_bubble.ts

@@ -5,7 +5,7 @@
  */
 
 export interface IHasBubble {
-  /** @return True if the bubble is currently open, false otherwise. */
+  /** @returns True if the bubble is currently open, false otherwise. */
   bubbleIsVisible(): boolean;
 
   /** Sets whether the bubble is open or not. */