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.
+      'jsdoc/check-tag-names': [
-      // Re-enable after Closure is removed.
+        'error',
-      'jsdoc/check-tag-names': ['off'],
+        {
+          '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,7 +2254,7 @@ 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 {
@@ -2263,14 +2262,14 @@ export class Block implements IASTNodeLocation, IDeletable {
   }
 
   /**
-   * @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. */

core/interfaces/i_icon.ts

@@ -9,7 +9,7 @@ import type {Size} from '../utils/size.js';
 
 export interface IIcon {
   /**
-   * @return the string representing the type of the icon.
+   * @returns the string representing the type of the icon.
    * E.g. 'comment', 'warning', etc. This string should also be used when
    * registering the icon class.
    */
@@ -35,13 +35,13 @@ export interface IIcon {
   dispose(): void;
 
   /**
-   * @return the "weight" of the icon, which determines the static order which
+   * @returns the "weight" of the icon, which determines the static order which
    *     icons should be rendered in. More positive numbers are rendered farther
    *     toward the end of the block.
    */
   getWeight(): number;
 
-  /** @return The dimensions of the icon for use in rendering. */
+  /** @returns The dimensions of the icon for use in rendering. */
   getSize(): Size;
 
   /** Updates the icon's color when the block's color changes.. */
@@ -60,7 +60,7 @@ export interface IIcon {
   updateCollapsed(): void;
 
   /**
-   * @return Whether this icon is shown when the block is collapsed. Used
+   * @returns Whether this icon is shown when the block is collapsed. Used
    *     to allow renderers to account for padding.
    */
   isShownWhenCollapsed(): boolean;

core/interfaces/i_serializable.ts

@@ -9,7 +9,7 @@ export interface ISerializable {
    * @param doFullSerialization If true, this signals that any backing data
    *     structures used by this ISerializable should also be serialized. This
    *     is used for copy-paste.
-   * @return a JSON serializable value that records the icon's state.
+   * @returns a JSON serializable value that records the icon's state.
    */
   saveState(doFullSerialization: boolean): any;
 

core/marker_manager.ts

@@ -174,7 +174,6 @@ export class MarkerManager {
    * Dispose of the marker manager.
    * Go through and delete all markers associated with this marker manager.
    *
-   * @suppress {checkTypes}
    * @internal
    */
   dispose() {

core/render_management.ts

@@ -27,7 +27,7 @@ let afterRendersPromise: Promise<void> | null = null;
  * and registers a callback to do so after a delay, to allowf or batching.
  *
  * @param block The block to rerender.
- * @return A promise that resolves after the currently queued renders have been
+ * @returns A promise that resolves after the currently queued renders have been
  *     completed. Used for triggering other behavior that relies on updated
  *     size/position location for the block.
  * @internal

core/rendered_connection.ts

@@ -191,7 +191,7 @@ export class RenderedConnection extends Connection {
    *
    * @param x New absolute x coordinate, in workspace coordinates.
    * @param y New absolute y coordinate, in workspace coordinates.
-   * @return True if the position of the connection in the connection db
+   * @returns True if the position of the connection in the connection db
    *     was updated.
    */
   moveTo(x: number, y: number): boolean {
@@ -224,7 +224,7 @@ export class RenderedConnection extends Connection {
    *
    * @param dx Change to x coordinate, in workspace units.
    * @param dy Change to y coordinate, in workspace units.
-   * @return True if the position of the connection in the connection db
+   * @returns True if the position of the connection in the connection db
    *     was updated.
    */
   moveBy(dx: number, dy: number): boolean {
@@ -237,7 +237,7 @@ export class RenderedConnection extends Connection {
    *
    * @param blockTL The location of the top left corner of the block, in
    *     workspace coordinates.
-   * @return True if the position of the connection in the connection db
+   * @returns True if the position of the connection in the connection db
    *     was updated.
    */
   moveToOffset(blockTL: Coordinate): boolean {

core/renderers/common/constants.ts

@@ -908,8 +908,6 @@ export class ConstantProvider {
    * @param svg The root of the workspace's SVG.
    * @param tagName The name to use for the CSS style tag.
    * @param selector The CSS selector to use.
-   * @suppress {strictModuleDepCheck} Debug renderer only included in
-   * playground.
    */
   createDom(svg: SVGElement, tagName: string, selector: string) {
     this.injectCSS_(tagName, selector);

core/scrollbar.ts

@@ -255,8 +255,6 @@ export class Scrollbar {
   /**
    * Dispose of this scrollbar. Remove DOM elements, event listeners,
    * and theme subscriptions.
-   *
-   * @suppress {checkTypes}
    */
   dispose() {
     this.cleanUp();

core/scrollbar_pair.ts

@@ -81,8 +81,6 @@ export class ScrollbarPair {
   /**
    * Dispose of this pair of scrollbars.
    * Unlink from all DOM elements to prevent memory leaks.
-   *
-   * @suppress {checkTypes}
    */
   dispose() {
     dom.removeNode(this.corner_);

core/theme_manager.ts

@@ -171,7 +171,6 @@ export class ThemeManager {
   /**
    * Dispose of this theme manager.
    *
-   * @suppress {checkTypes}
    * @internal
    */
   dispose() {

core/workspace.ts

@@ -151,8 +151,6 @@ export class Workspace implements IASTNodeLocation {
   /**
    * Dispose of this workspace.
    * Unlink from all DOM elements to prevent memory leaks.
-   *
-   * @suppress {checkTypes}
    */
   dispose() {
     this.listeners.length = 0;

core/workspace_dragger.ts

@@ -44,7 +44,6 @@ export class WorkspaceDragger {
   /**
    * Sever all links from this object.
    *
-   * @suppress {checkTypes}
    * @internal
    */
   dispose() {

core/workspace_svg.ts

@@ -812,8 +812,6 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg {
   /**
    * Dispose of this workspace.
    * Unlink from all DOM elements to prevent memory leaks.
-   *
-   * @suppress {checkTypes}
    */
   override dispose() {
     // Stop rerendering.
@@ -1428,8 +1426,6 @@ export class WorkspaceSvg extends Workspace implements IASTNodeLocationSvg {
    *
    * @param xmlComment XML workspace comment element.
    * @returns The pasted workspace comment.
-   * @suppress {checkTypes} Suppress checks while workspace comments are not
-   * bundled in.
    */
   private pasteWorkspaceComment_(xmlComment: Element): WorkspaceCommentSvg {
     eventUtils.disable();

core/xml.ts

@@ -398,8 +398,6 @@ export function clearWorkspaceAndLoadFromXml(
  * @param xml XML DOM.
  * @param workspace The workspace.
  * @returns An array containing new block IDs.
- * @suppress {strictModuleDepCheck} Suppress module check while workspace
- * comments are not bundled in.
  */
 export function domToWorkspace(xml: Element, workspace: Workspace): string[] {
   let width = 0; // Not used in LTR.

tsdoc.json

@@ -18,14 +18,6 @@
     {
       "tagName": "@nocollapse",
       "syntaxKind": "modifier"
-    },
-    {
-      "tagName": "@suppress",
-      "syntaxKind": "block"
-    },
-    {
-      "tagName": "@unrestricted",
-      "syntaxKind": "modifier"
     }
   ],
 

typings/msg/constants.d.ts

@@ -5,12 +5,10 @@
  */
 
 /**
- * @fileoverview Type definitions for the Blockly constants locale.
+ * Type definitions for the Blockly constants locale.
- * @author samelh@google.com (Sam El-Husseini)
  */
 
 /// <reference path="msg.d.ts" />
 
 import BlocklyMsg = Blockly.Msg;
 export = BlocklyMsg;
-

typings/msg/msg.d.ts

@@ -5,8 +5,7 @@
  */
 
 /**
- * @fileoverview Type definitions for Blockly Messages.
+ * Type definitions for Blockly Messages.
- * @author samelh@google.com (Sam El-Husseini)
  */
 
 

typings/msg/qqq.d.ts

@@ -5,12 +5,10 @@
  */
 
 /**
- * @fileoverview Type definitions for the Blockly qqq locale.
+ *  Type definitions for the Blockly qqq locale.
- * @author samelh@google.com (Sam El-Husseini)
  */
 
 /// <reference path="msg.d.ts" />
 
 import BlocklyMsg = Blockly.Msg;
 export = BlocklyMsg;
-

typings/msg/synonyms.d.ts

@@ -5,12 +5,10 @@
  */
 
 /**
- * @fileoverview Type definitions for the Blockly synonyms locale.
+ *  Type definitions for the Blockly synonyms locale.
- * @author samelh@google.com (Sam El-Husseini)
  */
 
 /// <reference path="msg.d.ts" />
 
 import BlocklyMsg = Blockly.Msg;
 export = BlocklyMsg;
-