chore: Lint TsDoc. (#6353)

* chore: add linting for tsdoc

* chore: don't require types on return

* chore: remove redundant fileoverview from ts

* chore: change return to returns and add some newlines

* chore: remove license tag

* chore: don't require params/return docs

* chore: remove spurious struct tags

* Revert "chore: change return to returns and add some newlines"

This reverts commit d6d8656a45.

* chore: don't auto-add param names

* chore: disable require-param bc it breaks on this

* return to returns and add line breaks

* chore: configure additional jsdoc rules

* chore: run format

* Revert "chore: remove license tag"

This reverts commit 173455588a.

* chore: allow license tag format

* chore: only require jsdoc on exported items

* chore: add missing jsdoc or silence where needed

* chore: run format

* chore: lint fixes

core/block.ts

@@ -4,12 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * @fileoverview The class representing one block.
- */
-
 /**
  * The class representing one block.
+ *
  * @class
  */
 import * as goog from '../closure/goog/goog.js';
@@ -53,6 +50,7 @@ import type {Workspace} from './workspace.js';
 /**
  * Class for one block.
  * Not normally called directly, workspace.newBlock() is preferred.
+ *
  * @unrestricted
  * @alias Blockly.Block
  */
@@ -78,6 +76,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Has this block been disposed of?
+   *
    * @internal
    */
   disposed = false;
@@ -184,6 +183,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * A string representing the comment attached to this block.
+   *
    * @deprecated August 2019. Use getCommentText instead.
    */
   comment: string|Comment|null = null;
@@ -214,6 +214,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * A count of statement inputs on the block.
+   *
    * @internal
    */
   statementInputCount = 0;
@@ -309,6 +310,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Dispose of this block.
+   *
    * @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.
@@ -380,6 +382,7 @@ export class Block implements IASTNodeLocation, IDeletable {
   /**
    * Unplug this block from its superior block.  If this block is a statement,
    * optionally reconnect the block underneath with the block on top.
+   *
    * @param opt_healStack Disconnect child statement and reconnect stack.
    *     Defaults to false.
    */
@@ -395,6 +398,7 @@ export class Block implements IASTNodeLocation, IDeletable {
   /**
    * Unplug this block's output from an input on another block.  Optionally
    * reconnect the block's parent to the only child block, if possible.
+   *
    * @param opt_healStack Disconnect right-side block and connect to left-side
    *     block.  Defaults to false.
    */
@@ -438,7 +442,7 @@ export class Block implements IASTNodeLocation, IDeletable {
    * Since only one block can be displaced and attached to the insertion marker
    * this should only ever return one connection.
    *
-   * @return The connection on the value input, or null.
+   * @returns The connection on the value input, or null.
    */
   private getOnlyValueConnection_(): Connection|null {
     let connection = null;
@@ -459,6 +463,7 @@ export class Block implements IASTNodeLocation, IDeletable {
   /**
    * Unplug this statement block from its superior block.  Optionally reconnect
    * the block underneath with the block on top.
+   *
    * @param opt_healStack Disconnect child statement and reconnect stack.
    *     Defaults to false.
    */
@@ -486,8 +491,9 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Returns all connections originating from this block.
+   *
    * @param _all If true, return all connections even hidden ones.
-   * @return Array of connections.
+   * @returns Array of connections.
    * @internal
    */
   getConnections_(_all: boolean): Connection[] {
@@ -512,10 +518,11 @@ export class Block implements IASTNodeLocation, IDeletable {
   /**
    * Walks down a stack of blocks and finds the last next connection on the
    * stack.
+   *
    * @param ignoreShadows If true,the last connection on a non-shadow block will
    *     be returned. If false, this will follow shadows to find the last
    *     connection.
-   * @return The last next connection on the stack, or null.
+   * @returns The last next connection on the stack, or null.
    * @internal
    */
   lastConnectionInStack(ignoreShadows: boolean): Connection|null {
@@ -542,7 +549,8 @@ export class Block implements IASTNodeLocation, IDeletable {
    * parent block is either the block connected to the previous connection (for
    * a statement block) or the block connected to the output connection (for a
    * value block).
-   * @return The block (if any) that holds the current block.
+   *
+   * @returns The block (if any) that holds the current block.
    */
   getParent(): this|null {
     return this.parentBlock_;
@@ -550,8 +558,9 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Return the input that connects to the specified block.
+   *
    * @param block A block connected to an input on this block.
-   * @return The input (if any) that connects to the specified block.
+   * @returns The input (if any) that connects to the specified block.
    */
   getInputWithBlock(block: Block): Input|null {
     for (let i = 0, input; input = this.inputList[i]; i++) {
@@ -567,7 +576,8 @@ export class Block implements IASTNodeLocation, IDeletable {
    * block has no surrounding block.  A parent block might just be the previous
    * statement, whereas the surrounding block is an if statement, while loop,
    * etc.
-   * @return The block (if any) that surrounds the current block.
+   *
+   * @returns The block (if any) that surrounds the current block.
    */
   getSurroundParent(): this|null {
     /* eslint-disable-next-line @typescript-eslint/no-this-alias */
@@ -589,7 +599,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Return the next statement block directly connected to this block.
-   * @return The next statement block or null.
+   *
+   * @returns The next statement block or null.
    */
   getNextBlock(): Block|null {
     return this.nextConnection && this.nextConnection.targetBlock();
@@ -597,7 +608,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Returns the block connected to the previous connection.
-   * @return The previous statement block or null.
+   *
+   * @returns The previous statement block or null.
    */
   getPreviousBlock(): Block|null {
     return this.previousConnection && this.previousConnection.targetBlock();
@@ -606,7 +618,8 @@ export class Block implements IASTNodeLocation, IDeletable {
   /**
    * Return the connection on the first statement input on this block, or null
    * if there are none.
-   * @return The first statement connection or null.
+   *
+   * @returns The first statement connection or null.
    * @internal
    */
   getFirstStatementConnection(): Connection|null {
@@ -622,7 +635,8 @@ export class Block implements IASTNodeLocation, IDeletable {
   /**
    * Return the top-most block in this block's tree.
    * This will return itself if this block is at the top level.
-   * @return The root block.
+   *
+   * @returns The root block.
    */
   getRootBlock(): this {
     let rootBlock: this;
@@ -639,7 +653,8 @@ export class Block implements IASTNodeLocation, IDeletable {
    * Walk up from the given block up through the stack of blocks to find
    * the top block of the sub stack. If we are nested in a statement input only
    * find the top-most nested block. Do not go all the way to the root block.
-   * @return The top block in a stack.
+   *
+   * @returns The top block in a stack.
    * @internal
    */
   getTopStackBlock(): this {
@@ -660,8 +675,9 @@ export class Block implements IASTNodeLocation, IDeletable {
    * Includes value and statement inputs, as well as any following statement.
    * Excludes any connection on an output tab or any preceding statement.
    * Blocks are optionally sorted by position; top to bottom.
+   *
    * @param ordered Sort the list if true.
-   * @return Array of blocks.
+   * @returns Array of blocks.
    */
   getChildren(ordered: boolean): Block[] {
     if (!ordered) {
@@ -685,6 +701,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set parent of this block to be a new block or null.
+   *
    * @param newParent New parent block.
    * @internal
    */
@@ -737,8 +754,9 @@ export class Block implements IASTNodeLocation, IDeletable {
    * Includes value and statement inputs, as well as any following statements.
    * Excludes any connection on an output tab or any preceding statements.
    * Blocks are optionally sorted by position; top to bottom.
+   *
    * @param ordered Sort the list if true.
-   * @return Flattened array of blocks.
+   * @returns Flattened array of blocks.
    */
   getDescendants(ordered: boolean): this[] {
     const blocks = [this];
@@ -753,7 +771,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Get whether this block is deletable or not.
-   * @return True if deletable.
+   *
+   * @returns True if deletable.
    */
   isDeletable(): boolean {
     return this.deletable_ && !this.isShadow_ && !this.disposed &&
@@ -762,6 +781,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set whether this block is deletable or not.
+   *
    * @param deletable True if deletable.
    */
   setDeletable(deletable: boolean) {
@@ -770,7 +790,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Get whether this block is movable or not.
-   * @return True if movable.
+   *
+   * @returns True if movable.
    */
   isMovable(): boolean {
     return this.movable_ && !this.isShadow_ && !this.disposed &&
@@ -779,6 +800,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set whether this block is movable or not.
+   *
    * @param movable True if movable.
    */
   setMovable(movable: boolean) {
@@ -790,7 +812,8 @@ export class Block implements IASTNodeLocation, IDeletable {
    * descendants will put this block over the workspace's capacity this block is
    * not duplicatable. If duplicating this block and descendants will put any
    * type over their maxInstances this block is not duplicatable.
-   * @return True if duplicatable.
+   *
+   * @returns True if duplicatable.
    */
   isDuplicatable(): boolean {
     if (!this.workspace.hasBlockLimits()) {
@@ -802,7 +825,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Get whether this block is a shadow block or not.
-   * @return True if a shadow.
+   *
+   * @returns True if a shadow.
    */
   isShadow(): boolean {
     return this.isShadow_;
@@ -810,6 +834,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set whether this block is a shadow block or not.
+   *
    * @param shadow True if a shadow.
    * @internal
    */
@@ -819,7 +844,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Get whether this block is an insertion marker block or not.
-   * @return True if an insertion marker.
+   *
+   * @returns True if an insertion marker.
    */
   isInsertionMarker(): boolean {
     return this.isInsertionMarker_;
@@ -828,6 +854,7 @@ export class Block implements IASTNodeLocation, IDeletable {
   /**
    * Set whether this block is an insertion marker block or not.
    * Once set this cannot be unset.
+   *
    * @param insertionMarker True if an insertion marker.
    * @internal
    */
@@ -837,7 +864,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Get whether this block is editable or not.
-   * @return True if editable.
+   *
+   * @returns True if editable.
    */
   isEditable(): boolean {
     return this.editable_ && !this.disposed && !this.workspace.options.readOnly;
@@ -845,6 +873,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set whether this block is editable or not.
+   *
    * @param editable True if editable.
    */
   setEditable(editable: boolean) {
@@ -858,7 +887,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Returns if this block has been disposed of / deleted.
-   * @return True if this block has been disposed of / deleted.
+   *
+   * @returns True if this block has been disposed of / deleted.
    */
   isDisposed(): boolean {
     return this.disposed;
@@ -868,9 +898,10 @@ export class Block implements IASTNodeLocation, IDeletable {
    * Find the connection on this block that corresponds to the given connection
    * on the other block.
    * Used to match connections between a block and its insertion marker.
+   *
    * @param otherBlock The other block to match against.
    * @param conn The other connection to match.
-   * @return The matching connection on this block, or null.
+   * @returns The matching connection on this block, or null.
    * @internal
    */
   getMatchingConnection(otherBlock: Block, conn: Connection): Connection|null {
@@ -889,6 +920,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set the URL of this block's help page.
+   *
    * @param url URL string for block help, or function that returns a URL.  Null
    *     for no help.
    */
@@ -898,6 +930,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Sets the tooltip for this block.
+   *
    * @param newTip The text for the tooltip, a function that returns the text
    *     for the tooltip, or a parent object whose tooltip will be used. To not
    *     display a tooltip pass the empty string.
@@ -908,7 +941,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Returns the tooltip text for this block.
-   * @return The tooltip text for this block.
+   *
+   * @returns The tooltip text for this block.
    */
   getTooltip(): string {
     return Tooltip.getTooltipOfObject(this);
@@ -916,7 +950,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Get the colour of a block.
-   * @return #RRGGBB string.
+   *
+   * @returns #RRGGBB string.
    */
   getColour(): string {
     return this.colour_;
@@ -924,7 +959,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Get the name of the block style.
-   * @return Name of the block style.
+   *
+   * @returns Name of the block style.
    */
   getStyleName(): string {
     return this.styleName_;
@@ -932,7 +968,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Get the HSV hue value of a block.  Null if hue not set.
-   * @return Hue value (0-360).
+   *
+   * @returns Hue value (0-360).
    */
   getHue(): number|null {
     return this.hue_;
@@ -940,6 +977,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Change the colour of a block.
+   *
    * @param colour HSV hue value (0 to 360), #RRGGBB string, or a message
    *     reference string pointing to one of those two values.
    */
@@ -951,6 +989,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set the style and colour values of a block.
+   *
    * @param blockStyleName Name of the block style.
    */
   setStyle(blockStyleName: string) {
@@ -962,6 +1001,7 @@ export class Block implements IASTNodeLocation, IDeletable {
    * changes, replacing any prior onchange handler. This is usually only called
    * from the constructor, the block type initializer function, or an extension
    * initializer function.
+   *
    * @param onchangeFn The callback to call when the block's workspace changes.
    * @throws {Error} if onchangeFn is not falsey and not a function.
    */
@@ -979,8 +1019,9 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Returns the named field from a block.
+   *
    * @param name The name of the field.
-   * @return Named field, or null if field does not exist.
+   * @returns Named field, or null if field does not exist.
    */
   getField(name: string): Field|null {
     if (typeof name !== 'string') {
@@ -1002,7 +1043,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Return all variables referenced by this block.
-   * @return List of variable ids.
+   *
+   * @returns List of variable ids.
    */
   getVars(): string[] {
     const vars = [];
@@ -1018,7 +1060,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Return all variables referenced by this block.
-   * @return List of variable models.
+   *
+   * @returns List of variable models.
    * @internal
    */
   getVarModels(): VariableModel[] {
@@ -1042,6 +1085,7 @@ export class Block implements IASTNodeLocation, IDeletable {
   /**
    * Notification that a variable is renaming but keeping the same ID.  If the
    * variable is in use on this block, rerender to show the new name.
+   *
    * @param variable The variable being renamed.
    * @internal
    */
@@ -1059,6 +1103,7 @@ export class Block implements IASTNodeLocation, IDeletable {
   /**
    * Notification that a variable is renaming.
    * If the ID matches one of this block's variables, rename it.
+   *
    * @param oldId ID of variable to rename.
    * @param newId ID of new variable.  May be the same as oldId, but with an
    *     updated name.
@@ -1075,8 +1120,9 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Returns the language-neutral value of the given field.
+   *
    * @param name The name of the field.
-   * @return Value of the field or null if field does not exist.
+   * @returns Value of the field or null if field does not exist.
    */
   getFieldValue(name: string): AnyDuringMigration {
     const field = this.getField(name);
@@ -1088,6 +1134,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Sets the value of the given field for this block.
+   *
    * @param newValue The value to set.
    * @param name The name of the field to set the value of.
    */
@@ -1101,6 +1148,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set whether this block can chain onto the bottom of another block.
+   *
    * @param newBoolean True if there can be a previous statement.
    * @param opt_check Statement type or list of statement types.  Null/undefined
    *     if any type could be connected.
@@ -1132,6 +1180,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set whether another block can chain onto the bottom of this block.
+   *
    * @param newBoolean True if there can be a next statement.
    * @param opt_check Statement type or list of statement types.  Null/undefined
    *     if any type could be connected.
@@ -1163,6 +1212,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set whether this block returns a value.
+   *
    * @param newBoolean True if there is an output.
    * @param opt_check Returned type or list of returned types.  Null or
    *     undefined if any type could be returned (e.g. variable get).
@@ -1193,6 +1243,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set whether value inputs are arranged horizontally or vertically.
+   *
    * @param newBoolean True if inputs are horizontal.
    */
   setInputsInline(newBoolean: boolean) {
@@ -1205,7 +1256,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Get whether value inputs are arranged horizontally or vertically.
-   * @return True if inputs are horizontal.
+   *
+   * @returns True if inputs are horizontal.
    */
   getInputsInline(): boolean {
     if (this.inputsInline !== undefined) {
@@ -1232,6 +1284,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set the block's output shape.
+   *
    * @param outputShape Value representing an output shape.
    */
   setOutputShape(outputShape: number|null) {
@@ -1240,7 +1293,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Get the block's output shape.
-   * @return Value representing output shape if one exists.
+   *
+   * @returns Value representing output shape if one exists.
    */
   getOutputShape(): number|null {
     return this.outputShape_;
@@ -1248,7 +1302,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Get whether this block is enabled or not.
-   * @return True if enabled.
+   *
+   * @returns True if enabled.
    */
   isEnabled(): boolean {
     return !this.disabled;
@@ -1256,6 +1311,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set whether the block is enabled or not.
+   *
    * @param enabled True if enabled.
    */
   setEnabled(enabled: boolean) {
@@ -1270,7 +1326,8 @@ export class Block implements IASTNodeLocation, IDeletable {
   /**
    * Get whether the block is disabled or not due to parents.
    * The block's own disabled property is not considered.
-   * @return True if disabled.
+   *
+   * @returns True if disabled.
    */
   getInheritedDisabled(): boolean {
     let ancestor = this.getSurroundParent();
@@ -1286,7 +1343,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Get whether the block is collapsed or not.
-   * @return True if collapsed.
+   *
+   * @returns True if collapsed.
    */
   isCollapsed(): boolean {
     return this.collapsed_;
@@ -1294,6 +1352,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set whether the block is collapsed or not.
+   *
    * @param collapsed True if collapsed.
    */
   setCollapsed(collapsed: boolean) {
@@ -1306,10 +1365,11 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Create a human-readable text representation of this block and any children.
+   *
    * @param opt_maxLength Truncate the string to this length.
    * @param opt_emptyToken The placeholder string used to denote an empty field.
    *     If not specified, '?' is used.
-   * @return Text of block.
+   * @returns Text of block.
    */
   toString(opt_maxLength?: number, opt_emptyToken?: string): string {
     let text = [];
@@ -1324,8 +1384,9 @@ export class Block implements IASTNodeLocation, IDeletable {
 
     /**
      * Whether or not to add parentheses around an input.
+     *
      * @param connection The connection.
-     * @return True if we should add parentheses around the input.
+     * @returns True if we should add parentheses around the input.
      */
     function shouldAddParentheses(connection: Connection): boolean {
       let checks = connection.getCheck();
@@ -1424,9 +1485,10 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Shortcut for appending a value input row.
+   *
    * @param name Language-neutral identifier which may used to find this input
    *     again.  Should be unique to this block.
-   * @return The input object created.
+   * @returns The input object created.
    */
   appendValueInput(name: string): Input {
     return this.appendInput_(inputTypes.VALUE, name);
@@ -1434,9 +1496,10 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Shortcut for appending a statement input row.
+   *
    * @param name Language-neutral identifier which may used to find this input
    *     again.  Should be unique to this block.
-   * @return The input object created.
+   * @returns The input object created.
    */
   appendStatementInput(name: string): Input {
     return this.appendInput_(inputTypes.STATEMENT, name);
@@ -1444,9 +1507,10 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Shortcut for appending a dummy input row.
+   *
    * @param opt_name Language-neutral identifier which may used to find this
    *     input again.  Should be unique to this block.
-   * @return The input object created.
+   * @returns The input object created.
    */
   appendDummyInput(opt_name?: string): Input {
     return this.appendInput_(inputTypes.DUMMY, opt_name || '');
@@ -1455,6 +1519,7 @@ export class Block implements IASTNodeLocation, IDeletable {
   /**
    * Initialize this block using a cross-platform, internationalization-friendly
    * JSON description.
+   *
    * @param json Structured data describing the block.
    */
   jsonInit(json: AnyDuringMigration) {
@@ -1549,6 +1614,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Initialize the colour of this block from the JSON description.
+   *
    * @param json Structured data describing the block.
    * @param warningPrefix Warning prefix string identifying block.
    */
@@ -1569,6 +1635,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Initialize the style of this block from the JSON description.
+   *
    * @param json Structured data describing the block.
    * @param warningPrefix Warning prefix string identifying block.
    */
@@ -1587,6 +1654,7 @@ export class Block implements IASTNodeLocation, IDeletable {
    * the block, including prototype values. This provides some insurance against
    * mixin / extension incompatibilities with future block features. This check
    * can be disabled by passing true as the second argument.
+   *
    * @param mixinObj The key/values pairs to add to this block object.
    * @param opt_disableCheck Option flag to disable overwrite checks.
    */
@@ -1613,6 +1681,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Interpolate a message description onto the block.
+   *
    * @param message Text contains interpolation tokens (%1, %2, ...) that match
    *     with fields or inputs defined in the args array.
    * @param args Array of arguments to be interpolated.
@@ -1654,6 +1723,7 @@ export class Block implements IASTNodeLocation, IDeletable {
    * Validates that the tokens are within the correct bounds, with no
    * duplicates, and that all of the arguments are referred to. Throws errors if
    * any of these things are not true.
+   *
    * @param tokens An array of tokens to validate
    * @param argsCount The number of args that need to be referred to.
    */
@@ -1689,11 +1759,12 @@ export class Block implements IASTNodeLocation, IDeletable {
    * Inserts args in place of numerical tokens. String args are converted to
    * JSON that defines a label field. If necessary an extra dummy input is added
    * to the end of the elements.
+   *
    * @param tokens The tokens to interpolate
    * @param args The arguments to insert.
    * @param lastDummyAlign The alignment the added dummy input should have, if
    *     we are required to add one.
-   * @return The JSON definitions of field and inputs to add to the block.
+   * @returns The JSON definitions of field and inputs to add to the block.
    */
   private interpolateArguments_(
       tokens: Array<string|number>, args: Array<AnyDuringMigration|string>,
@@ -1734,8 +1805,9 @@ export class Block implements IASTNodeLocation, IDeletable {
    * Creates a field from the JSON definition of a field. If a field with the
    * given type cannot be found, this attempts to create a different field using
    * the 'alt' property of the JSON definition (if it exists).
+   *
    * @param element The element to try to turn into a field.
-   * @return The field defined by the JSON, or null if one couldn't be created.
+   * @returns The field defined by the JSON, or null if one couldn't be created.
    */
   private fieldFromJson_(element: {alt?: string, type?: string, text?: string}):
       Field|null {
@@ -1753,10 +1825,11 @@ export class Block implements IASTNodeLocation, IDeletable {
   /**
    * Creates an input from the JSON definition of an input. Sets the input's
    * check and alignment if they are provided.
+   *
    * @param element The JSON to turn into an input.
    * @param warningPrefix The prefix to add to warnings to help the developer
    *     debug.
-   * @return The input that has been created, or null if one could not be
+   * @returns The input that has been created, or null if one could not be
    *     created for some reason (should never happen).
    */
   private inputFromJson_(element: AnyDuringMigration, warningPrefix: string):
@@ -1803,8 +1876,9 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Returns true if the given string matches one of the input keywords.
+   *
    * @param str The string to check.
-   * @return True if the given string matches one of the input keywords, false
+   * @returns True if the given string matches one of the input keywords, false
    *     otherwise.
    */
   private isInputKeyword_(str: string): boolean {
@@ -1815,8 +1889,9 @@ export class Block implements IASTNodeLocation, IDeletable {
   /**
    * Turns a string into the JSON definition of a label field. If the string
    * becomes an empty string when trimmed, this returns null.
+   *
    * @param str String to turn into the JSON definition of a label field.
-   * @return The JSON definition or null.
+   * @returns The JSON definition or null.
    */
   private stringToFieldJson_(str: string): {text: string, type: string}|null {
     str = str.trim();
@@ -1831,10 +1906,11 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Add a value input, statement input or local variable to this block.
+   *
    * @param type One of Blockly.inputTypes.
    * @param name Language-neutral identifier which may used to find this input
    *     again.  Should be unique to this block.
-   * @return The input object created.
+   * @returns The input object created.
    */
   protected appendInput_(type: number, name: string): Input {
     let connection = null;
@@ -1855,6 +1931,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Move a named input to a different location on this block.
+   *
    * @param name The name of the input to move.
    * @param refName Name of input that should be after the moved input, or null
    *     to be the input at the end.
@@ -1890,6 +1967,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Move a numbered input to a different location on this block.
+   *
    * @param inputIndex Index of the input to move.
    * @param refIndex Index of input that should be after the moved input.
    */
@@ -1916,9 +1994,10 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Remove an input from this block.
+   *
    * @param name The name of the input.
    * @param opt_quiet True to prevent an error if input is not present.
-   * @return True if operation succeeds, false if input is not present and
+   * @returns True if operation succeeds, false if input is not present and
    *     opt_quiet is true.
    * @throws {Error} if the input is not present and opt_quiet is not true.
    */
@@ -1941,8 +2020,9 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Fetches the named input object.
+   *
    * @param name The name of the input.
-   * @return The input object, or null if input does not exist.
+   * @returns The input object, or null if input does not exist.
    */
   getInput(name: string): Input|null {
     for (let i = 0, input; input = this.inputList[i]; i++) {
@@ -1956,8 +2036,9 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Fetches the block attached to the named input.
+   *
    * @param name The name of the input.
-   * @return The attached value block, or null if the input is either
+   * @returns The attached value block, or null if the input is either
    *     disconnected or if the input does not exist.
    */
   getInputTargetBlock(name: string): Block|null {
@@ -1967,7 +2048,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Returns the comment on this block (or null if there is no comment).
-   * @return Block's comment.
+   *
+   * @returns Block's comment.
    */
   getCommentText(): string|null {
     return this.commentModel.text;
@@ -1975,6 +2057,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set this block's comment text.
+   *
    * @param text The text, or null to delete.
    */
   setCommentText(text: string|null) {
@@ -1991,6 +2074,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set this block's warning text.
+   *
    * @param _text The text, or null to delete.
    * @param _opt_id An optional ID for the warning text to be able to maintain
    *     multiple warnings.
@@ -2000,6 +2084,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Give this block a mutator dialog.
+   *
    * @param _mutator A mutator dialog instance or null to remove.
    */
   setMutator(_mutator: Mutator) {}
@@ -2008,7 +2093,8 @@ export class Block implements IASTNodeLocation, IDeletable {
   /**
    * Return the coordinates of the top-left corner of this block relative to the
    * drawing surface's origin (0,0), in workspace units.
-   * @return Object with .x and .y properties.
+   *
+   * @returns Object with .x and .y properties.
    */
   getRelativeToSurfaceXY(): Coordinate {
     return this.xy_;
@@ -2016,6 +2102,7 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Move a block by a relative offset.
+   *
    * @param dx Horizontal offset, in workspace units.
    * @param dy Vertical offset, in workspace units.
    */
@@ -2032,8 +2119,9 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Create a connection of the specified type.
+   *
    * @param type The type of the connection to create.
-   * @return A new connection of the specified type.
+   * @returns A new connection of the specified type.
    */
   protected makeConnection_(type: number): Connection {
     return new Connection(this, type);
@@ -2042,9 +2130,10 @@ export class Block implements IASTNodeLocation, IDeletable {
   /**
    * Recursively checks whether all statement and value inputs are filled with
    * blocks. Also checks all following statement blocks in this stack.
+   *
    * @param opt_shadowBlocksAreFilled An optional argument controlling whether
    *     shadow blocks are counted as filled. Defaults to true.
-   * @return True if all inputs are filled, false otherwise.
+   * @returns True if all inputs are filled, false otherwise.
    */
   allInputsFilled(opt_shadowBlocksAreFilled?: boolean): boolean {
     // Account for the shadow block filledness toggle.
@@ -2082,7 +2171,8 @@ export class Block implements IASTNodeLocation, IDeletable {
    * Intended to on be used in console logs and errors. If you need a string
    * that uses the user's native language (including block text, field values,
    * and child blocks), use [toString()]{@link Block#toString}.
-   * @return The description.
+   *
+   * @returns The description.
    */
   toDevString(): string {
     let msg = this.type ? '"' + this.type + '" block' : 'Block';