chore: change return to returns and add some newlines

2026-03-14 09:10:09 +01:00 · 2022-08-16 16:13:39 -07:00
parent 169959bc08
commit d6d8656a45
172 changed files with 2752 additions and 772 deletions
--- a/core/utils/aria.ts
+++ b/core/utils/aria.ts
@@ -8,6 +8,7 @@
 * ARIA-related constants and utilities.
 * These methods are not specific to Blockly, and could be factored out into
 * a JavaScript framework such as Closure.
+ *
 * @namespace Blockly.utils.aria
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -23,6 +24,7 @@ const ROLE_ATTRIBUTE = 'role';
 /**
 * ARIA role values.
 * Copied from Closure's goog.a11y.aria.Role
+ *
 * @alias Blockly.utils.aria.Role
 */
 export enum Role {
@@ -62,6 +64,7 @@ export enum Role {
 /**
 * ARIA states and properties.
 * Copied from Closure's goog.a11y.aria.State
+ *
 * @alias Blockly.utils.aria.State
 */
 export enum State {
@@ -135,6 +138,7 @@ export function setRole(element: Element, roleName: Role) {
 /**
 * Sets the state or property of an element.
 * Copied from Closure's goog.a11y.aria
+ *
 * @param element DOM node where we set state.
 * @param stateName State attribute being set.
 *     Automatically adds prefix 'aria-' to the state name if the attribute is
--- a/core/utils/array.ts
+++ b/core/utils/array.ts
@@ -11,9 +11,10 @@ goog.declareModuleId('Blockly.utils.array');

 /**
 * Removes the first occurrence of a particular value from an array.
+ *
 * @param arr Array from which to remove value.
 * @param value Value to remove.
- * @return True if an element was removed.
+ * @returns True if an element was removed.
 * @alias Blockly.array.removeElem
 * @internal
 */
--- a/core/utils/colour.ts
+++ b/core/utils/colour.ts
@@ -6,6 +6,7 @@

 /**
 * Utility methods for colour manipulation.
+ *
 * @namespace Blockly.utils.colour
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -15,14 +16,16 @@ goog.declareModuleId('Blockly.utils.colour');
 /**
 * The richness of block colours, regardless of the hue.
 * Must be in the range of 0 (inclusive) to 1 (exclusive).
+ *
 * @alias Blockly.utils.colour.hsvSaturation
 */
 let hsvSaturation = 0.45;

 /**
 * Get the richness of block colours, regardless of the hue.
+ *
 * @alias Blockly.utils.colour.getHsvSaturation
- * @return The current richness.
+ * @returns The current richness.
 * @internal
 */
 export function getHsvSaturation(): number {
@@ -31,6 +34,7 @@ export function getHsvSaturation(): number {

 /**
 * Set the richness of block colours, regardless of the hue.
+ *
 * @param newSaturation The new richness, in the range of  0 (inclusive) to 1
 *     (exclusive)
 * @alias Blockly.utils.colour.setHsvSaturation
@@ -43,14 +47,16 @@ export function setHsvSaturation(newSaturation: number) {
 /**
 * The intensity of block colours, regardless of the hue.
 * Must be in the range of 0 (inclusive) to 1 (exclusive).
+ *
 * @alias Blockly.utils.colour.hsvValue
 */
 let hsvValue = 0.65;

 /**
 * Get the intensity of block colours, regardless of the hue.
+ *
 * @alias Blockly.utils.colour.getHsvValue
- * @return The current intensity.
+ * @returns The current intensity.
 * @internal
 */
 export function getHsvValue(): number {
@@ -59,6 +65,7 @@ export function getHsvValue(): number {

 /**
 * Set the intensity of block colours, regardless of the hue.
+ *
 * @param newValue The new intensity, in the range of  0 (inclusive) to 1
 *     (exclusive)
 * @alias Blockly.utils.colour.setHsvValue
@@ -75,8 +82,9 @@ export function setHsvValue(newValue: number) {
 * .parse('#ff0000') -> '#ff0000'
 * .parse('0xff0000') -> '#ff0000'
 * .parse('rgb(255, 0, 0)') -> '#ff0000'
+ *
 * @param str Colour in some CSS format.
- * @return A string containing a hex representation of the colour, or null if
+ * @returns A string containing a hex representation of the colour, or null if
 *     can't be parsed.
 * @alias Blockly.utils.colour.parse
 */
@@ -112,10 +120,11 @@ export function parse(str: string|number): string|null {

 /**
 * Converts a colour from RGB to hex representation.
+ *
 * @param r Amount of red, int between 0 and 255.
 * @param g Amount of green, int between 0 and 255.
 * @param b Amount of blue, int between 0 and 255.
- * @return Hex representation of the colour.
+ * @returns Hex representation of the colour.
 * @alias Blockly.utils.colour.rgbToHex
 */
 export function rgbToHex(r: number, g: number, b: number): string {
@@ -128,9 +137,10 @@ export function rgbToHex(r: number, g: number, b: number): string {

 /**
 * Converts a colour to RGB.
+ *
 * @param colour String representing colour in any colour format ('#ff0000',
 *     'red', '0xff000', etc).
- * @return RGB representation of the colour.
+ * @returns RGB representation of the colour.
 * @alias Blockly.utils.colour.hexToRgb
 */
 export function hexToRgb(colour: string): number[] {
@@ -149,10 +159,11 @@ export function hexToRgb(colour: string): number[] {

 /**
 * Converts an HSV triplet to hex representation.
+ *
 * @param h Hue value in [0, 360].
 * @param s Saturation value in [0, 1].
 * @param v Brightness in [0, 255].
- * @return Hex representation of the colour.
+ * @returns Hex representation of the colour.
 * @alias Blockly.utils.colour.hsvToHex
 */
 export function hsvToHex(h: number, s: number, v: number): string {
@@ -209,11 +220,12 @@ export function hsvToHex(h: number, s: number, v: number): string {
 /**
 * Blend two colours together, using the specified factor to indicate the
 * weight given to the first colour.
+ *
 * @param colour1 First colour.
 * @param colour2 Second colour.
 * @param factor The weight to be given to colour1 over colour2.
 *     Values should be in the range [0, 1].
- * @return Combined colour represented in hex.
+ * @returns Combined colour represented in hex.
 * @alias Blockly.utils.colour.blend
 */
 export function blend(colour1: string, colour2: string, factor: number): string|
@@ -263,8 +275,9 @@ export const names: {[key: string]: string} = {

 /**
 * Convert a hue (HSV model) into an RGB hex triplet.
+ *
 * @param hue Hue on a colour wheel (0-360).
- * @return RGB code, e.g. '#5ba65b'.
+ * @returns RGB code, e.g. '#5ba65b'.
 * @alias Blockly.utils.colour.hueToHex
 */
 export function hueToHex(hue: number): string {
--- a/core/utils/coordinate.ts
+++ b/core/utils/coordinate.ts
@@ -8,6 +8,7 @@
 * Utility methods for coordinate manipulation.
 * These methods are not specific to Blockly, and could be factored out into
 * a JavaScript framework such as Closure.
+ *
 * @class
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -16,6 +17,7 @@ goog.declareModuleId('Blockly.utils.Coordinate');

 /**
 * Class for representing coordinates and positions.
+ *
 * @alias Blockly.utils.Coordinate
 */
 export class Coordinate {
@@ -27,7 +29,8 @@ export class Coordinate {

  /**
   * Creates a new copy of this coordinate.
-   * @return A copy of this coordinate.
+   *
+   * @returns A copy of this coordinate.
   */
  clone(): Coordinate {
    return new Coordinate(this.x, this.y);
@@ -35,8 +38,9 @@ export class Coordinate {

  /**
   * Scales this coordinate by the given scale factor.
+   *
   * @param s The scale factor to use for both x and y dimensions.
-   * @return This coordinate after scaling.
+   * @returns This coordinate after scaling.
   */
  scale(s: number): Coordinate {
    this.x *= s;
@@ -47,9 +51,10 @@ export class Coordinate {
  /**
   * Translates this coordinate by the given offsets.
   * respectively.
+   *
   * @param tx The value to translate x by.
   * @param ty The value to translate y by.
-   * @return This coordinate after translating.
+   * @returns This coordinate after translating.
   */
  translate(tx: number, ty: number): Coordinate {
    this.x += tx;
@@ -59,9 +64,10 @@ export class Coordinate {

  /**
   * Compares coordinates for equality.
+   *
   * @param a A Coordinate.
   * @param b A Coordinate.
-   * @return True iff the coordinates are equal, or if both are null.
+   * @returns True iff the coordinates are equal, or if both are null.
   */
  static equals(a: Coordinate|null, b: Coordinate|null): boolean {
    if (a === b) {
@@ -75,9 +81,10 @@ export class Coordinate {

  /**
   * Returns the distance between two coordinates.
+   *
   * @param a A Coordinate.
   * @param b A Coordinate.
-   * @return The distance between `a` and `b`.
+   * @returns The distance between `a` and `b`.
   */
  static distance(a: Coordinate, b: Coordinate): number {
    const dx = a.x - b.x;
@@ -87,8 +94,9 @@ export class Coordinate {

  /**
   * Returns the magnitude of a coordinate.
+   *
   * @param a A Coordinate.
-   * @return The distance between the origin and `a`.
+   * @returns The distance between the origin and `a`.
   */
  static magnitude(a: Coordinate): number {
    return Math.sqrt(a.x * a.x + a.y * a.y);
@@ -97,9 +105,10 @@ export class Coordinate {
  /**
   * Returns the difference between two coordinates as a new
   * Coordinate.
+   *
   * @param a An x/y coordinate.
   * @param b An x/y coordinate.
-   * @return A Coordinate representing the difference between `a` and `b`.
+   * @returns A Coordinate representing the difference between `a` and `b`.
   */
  static difference(a: Coordinate|SVGPoint, b: Coordinate|SVGPoint):
      Coordinate {
@@ -108,9 +117,10 @@ export class Coordinate {

  /**
   * Returns the sum of two coordinates as a new Coordinate.
+   *
   * @param a An x/y coordinate.
   * @param b An x/y coordinate.
-   * @return A Coordinate representing the sum of the two coordinates.
+   * @returns A Coordinate representing the sum of the two coordinates.
   */
  static sum(a: Coordinate|SVGPoint, b: Coordinate|SVGPoint): Coordinate {
    return new Coordinate(a.x + b.x, a.y + b.y);
--- a/core/utils/deprecation.ts
+++ b/core/utils/deprecation.ts
@@ -7,6 +7,7 @@
 /**
 * Helper function for warning developers about deprecations.
 * This method is not specific to Blockly.
+ *
 * @namespace Blockly.utils.deprecation
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -15,6 +16,7 @@ goog.declareModuleId('Blockly.utils.deprecation');

 /**
 * Warn developers that a function or property is deprecated.
+ *
 * @param name The name of the function or property.
 * @param deprecationDate The date of deprecation.
 *     Prefer 'month yyyy' or 'quarter yyyy' format.
--- a/core/utils/dom.ts
+++ b/core/utils/dom.ts
@@ -8,6 +8,7 @@
 * Utility methods for DOM manipulation.
 * These methods are not specific to Blockly, and could be factored out into
 * a JavaScript framework such as Closure.
+ *
 * @namespace Blockly.utils.dom
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -19,18 +20,21 @@ import * as userAgent from './useragent.js';

 /**
 * Required name space for SVG elements.
+ *
 * @alias Blockly.utils.dom.SVG_NS
 */
 export const SVG_NS = 'http://www.w3.org/2000/svg';

 /**
 * Required name space for HTML elements.
+ *
 * @alias Blockly.utils.dom.HTML_NS
 */
 export const HTML_NS = 'http://www.w3.org/1999/xhtml';

 /**
 * Required name space for XLINK elements.
+ *
 * @alias Blockly.utils.dom.XLINK_NS
 */
 export const XLINK_NS = 'http://www.w3.org/1999/xlink';
@@ -38,6 +42,7 @@ export const XLINK_NS = 'http://www.w3.org/1999/xlink';
 /**
 * Node type constants.
 * https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeType
+ *
 * @alias Blockly.utils.dom.NodeType
 */
 export enum NodeType {
@@ -60,10 +65,11 @@ let canvasContext: CanvasRenderingContext2D = null as AnyDuringMigration;

 /**
 * Helper method for creating SVG elements.
+ *
 * @param name Element's tag name.
 * @param attrs Dictionary of attribute names and values.
 * @param opt_parent Optional parent on which to append the element.
- * @return if name is a string or a more specific type if it a member of Svg.
+ * @returns if name is a string or a more specific type if it a member of Svg.
 * @alias Blockly.utils.dom.createSvgElement
 */
 export function createSvgElement<T extends SVGElement>(
@@ -88,9 +94,10 @@ export function createSvgElement<T extends SVGElement>(
 /**
 * Add a CSS class to a element.
 * Similar to Closure's goog.dom.classes.add, except it handles SVG elements.
+ *
 * @param element DOM element to add class to.
 * @param className Name of class to add.
- * @return True if class was added, false if already present.
+ * @returns True if class was added, false if already present.
 * @alias Blockly.utils.dom.addClass
 */
 export function addClass(element: Element, className: string): boolean {
@@ -107,6 +114,7 @@ export function addClass(element: Element, className: string): boolean {

 /**
 * Removes multiple calsses from an element.
+ *
 * @param element DOM element to remove classes from.
 * @param classNames A string of one or multiple class names for an element.
 * @alias Blockly.utils.dom.removeClasses
@@ -121,9 +129,10 @@ export function removeClasses(element: Element, classNames: string) {
 /**
 * Remove a CSS class from a element.
 * Similar to Closure's goog.dom.classes.remove, except it handles SVG elements.
+ *
 * @param element DOM element to remove class from.
 * @param className Name of class to remove.
- * @return True if class was removed, false if never present.
+ * @returns True if class was removed, false if never present.
 * @alias Blockly.utils.dom.removeClass
 */
 export function removeClass(element: Element, className: string): boolean {
@@ -149,9 +158,10 @@ export function removeClass(element: Element, className: string): boolean {
 /**
 * Checks if an element has the specified CSS class.
 * Similar to Closure's goog.dom.classes.has, except it handles SVG elements.
+ *
 * @param element DOM element to check.
 * @param className Name of class to check.
- * @return True if class exists, false otherwise.
+ * @returns True if class exists, false otherwise.
 * @alias Blockly.utils.dom.hasClass
 */
 export function hasClass(element: Element, className: string): boolean {
@@ -161,8 +171,9 @@ export function hasClass(element: Element, className: string): boolean {

 /**
 * Removes a node from its parent. No-op if not attached to a parent.
+ *
 * @param node The node to remove.
- * @return The node removed if removed; else, null.
+ * @returns The node removed if removed; else, null.
 * @alias Blockly.utils.dom.removeNode
 */
 // Copied from Closure goog.dom.removeNode
@@ -173,6 +184,7 @@ export function removeNode(node: Node|null): Node|null {
 /**
 * Insert a node after a reference node.
 * Contrast with node.insertBefore function.
+ *
 * @param newNode New element to insert.
 * @param refNode Existing element to precede new node.
 * @alias Blockly.utils.dom.insertAfter
@@ -192,9 +204,10 @@ export function insertAfter(newNode: Element, refNode: Element) {

 /**
 * Whether a node contains another node.
+ *
 * @param parent The node that should contain the other node.
 * @param descendant The node to test presence of.
- * @return Whether the parent node contains the descendant node.
+ * @returns Whether the parent node contains the descendant node.
 * @alias Blockly.utils.dom.containsNode
 */
 export function containsNode(parent: Node, descendant: Node): boolean {
@@ -207,6 +220,7 @@ export function containsNode(parent: Node, descendant: Node): boolean {
 * Sets the CSS transform property on an element. This function sets the
 * non-vendor-prefixed and vendor-prefixed versions for backwards compatibility
 * with older browsers. See https://caniuse.com/#feat=transforms2d
+ *
 * @param element Element to which the CSS transform will be applied.
 * @param transform The value of the CSS `transform` property.
 * @alias Blockly.utils.dom.setCssTransform
@@ -223,6 +237,7 @@ export function setCssTransform(element: Element, transform: string) {
 /**
 * Start caching text widths. Every call to this function MUST also call
 * stopTextWidthCache. Caches must not survive between execution threads.
+ *
 * @alias Blockly.utils.dom.startTextWidthCache
 */
 export function startTextWidthCache() {
@@ -235,6 +250,7 @@ export function startTextWidthCache() {
 /**
 * Stop caching field widths. Unless caching was already on when the
 * corresponding call to startTextWidthCache was made.
+ *
 * @alias Blockly.utils.dom.stopTextWidthCache
 */
 export function stopTextWidthCache() {
@@ -246,8 +262,9 @@ export function stopTextWidthCache() {

 /**
 * Gets the width of a text element, caching it in the process.
+ *
 * @param textElement An SVG 'text' element.
- * @return Width of element.
+ * @returns Width of element.
 * @alias Blockly.utils.dom.getTextWidth
 */
 export function getTextWidth(textElement: SVGTextElement): number {
@@ -287,11 +304,12 @@ export function getTextWidth(textElement: SVGTextElement): number {
 * Gets the width of a text element using a faster method than `getTextWidth`.
 * This method requires that we know the text element's font family and size in
 * advance. Similar to `getTextWidth`, we cache the width we compute.
+ *
 * @param textElement An SVG 'text' element.
 * @param fontSize The font size to use.
 * @param fontWeight The font weight to use.
 * @param fontFamily The font family to use.
- * @return Width of element.
+ * @returns Width of element.
 * @alias Blockly.utils.dom.getFastTextWidth
 */
 export function getFastTextWidth(
@@ -307,11 +325,12 @@ export function getFastTextWidth(
 * advance. Similar to `getTextWidth`, we cache the width we compute.
 * This method is similar to ``getFastTextWidth`` but expects the font size
 * parameter to be a string.
+ *
 * @param textElement An SVG 'text' element.
 * @param fontSize The font size to use.
 * @param fontWeight The font weight to use.
 * @param fontFamily The font family to use.
- * @return Width of element.
+ * @returns Width of element.
 * @alias Blockly.utils.dom.getFastTextWidthWithSizeString
 */
 export function getFastTextWidthWithSizeString(
@@ -360,11 +379,12 @@ export function getFastTextWidthWithSizeString(

 /**
 * Measure a font's metrics. The height and baseline values.
+ *
 * @param text Text to measure the font dimensions of.
 * @param fontSize The font size to use.
 * @param fontWeight The font weight to use.
 * @param fontFamily The font family to use.
- * @return Font measurements.
+ * @returns Font measurements.
 * @alias Blockly.utils.dom.measureFontMetrics
 */
 export function measureFontMetrics(
--- a/core/utils/idgenerator.ts
+++ b/core/utils/idgenerator.ts
@@ -6,6 +6,7 @@

 /**
 * Generators for unique IDs.
+ *
 * @namespace Blockly.utils.idGenerator
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -15,6 +16,7 @@ goog.declareModuleId('Blockly.utils.idGenerator');
 /**
 * Namespace object for internal implementations we want to be able to
 * stub in tests.
+ *
 * @ignore
 */
 const internal = {};
@@ -31,7 +33,7 @@ let nextId = 0;
 * For UUIDs use genUid (below) instead; this ID generator should
 * primarily be used for IDs that end up in the DOM.
 *
- * @return The next unique identifier.
+ * @returns The next unique identifier.
 * @alias Blockly.utils.idGenerator.getNextUniqueId
 */
 export function getNextUniqueId(): string {
@@ -51,7 +53,8 @@ const soup = '!#$%()*+,-./:;=?@[]^_`{|}~' +
 /**
 * Generate a random unique ID.  This should be globally unique.
 * 87 characters ^ 20 length > 128 bits (better than a UUID).
- * @return A globally unique ID string.
+ *
+ * @returns A globally unique ID string.
 */
 // AnyDuringMigration because:  Property 'genUid' does not exist on type '{}'.
 (internal as AnyDuringMigration).genUid = function(): string {
@@ -66,8 +69,9 @@ const soup = '!#$%()*+,-./:;=?@[]^_`{|}~' +

 /**
 * Generate a random unique ID.
+ *
 * @see internal.genUid
- * @return A globally unique ID string.
+ * @returns A globally unique ID string.
 * @alias Blockly.utils.idGenerator.genUid
 */
 export function genUid(): string {
--- a/core/utils/keycodes.ts
+++ b/core/utils/keycodes.ts
@@ -8,6 +8,7 @@
 * Constant declarations for common key codes.
 * These methods are not specific to Blockly, and could be factored out into
 * a JavaScript framework such as Closure.
+ *
 * @namespace Blockly.utils.KeyCodes
 */
 import * as goog from '../../closure/goog/goog.js';
--- a/core/utils/math.ts
+++ b/core/utils/math.ts
@@ -8,6 +8,7 @@
 * Utility methods for math.
 * These methods are not specific to Blockly, and could be factored out into
 * a JavaScript framework such as Closure.
+ *
 * @namespace Blockly.utils.math
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -17,8 +18,9 @@ goog.declareModuleId('Blockly.utils.math');
 /**
 * Converts degrees to radians.
 * Copied from Closure's goog.math.toRadians.
+ *
 * @param angleDegrees Angle in degrees.
- * @return Angle in radians.
+ * @returns Angle in radians.
 * @alias Blockly.utils.math.toRadians
 */
 export function toRadians(angleDegrees: number): number {
@@ -28,8 +30,9 @@ export function toRadians(angleDegrees: number): number {
 /**
 * Converts radians to degrees.
 * Copied from Closure's goog.math.toDegrees.
+ *
 * @param angleRadians Angle in radians.
- * @return Angle in degrees.
+ * @returns Angle in degrees.
 * @alias Blockly.utils.math.toDegrees
 */
 export function toDegrees(angleRadians: number): number {
@@ -38,10 +41,11 @@ export function toDegrees(angleRadians: number): number {

 /**
 * Clamp the provided number between the lower bound and the upper bound.
+ *
 * @param lowerBound The desired lower bound.
 * @param number The number to clamp.
 * @param upperBound The desired upper bound.
- * @return The clamped number.
+ * @returns The clamped number.
 * @alias Blockly.utils.math.clamp
 */
 export function clamp(
--- a/core/utils/metrics.ts
+++ b/core/utils/metrics.ts
@@ -6,6 +6,7 @@

 /**
 * Workspace metrics definitions.
+ *
 * @namespace Blockly.utils.Metrics
 */
 import * as goog from '../../closure/goog/goog.js';
--- a/core/utils/object.ts
+++ b/core/utils/object.ts
@@ -6,6 +6,7 @@

 /**
 * Utility methods for objects.
+ *
 * @namespace Blockly.utils.object
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -16,6 +17,7 @@ import * as deprecation from './deprecation.js';

 /**
 * Inherit the prototype methods from one constructor into another.
+ *
 * @param childCtor Child class.
 * @param parentCtor Parent class.
 * @suppress {strictMissingProperties} superClass_ is not defined on Function.
@@ -42,6 +44,7 @@ export function inherits(childCtor: Function, parentCtor: Function) {

 /**
 * Copies all the members of a source object to a target object.
+ *
 * @param target Target.
 * @param source Source.
 * @alias Blockly.utils.object.mixin
@@ -56,9 +59,10 @@ export function mixin(target: AnyDuringMigration, source: AnyDuringMigration) {

 /**
 * Complete a deep merge of all members of a source object with a target object.
+ *
 * @param target Target.
 * @param source Source.
- * @return The resulting object.
+ * @returns The resulting object.
 * @alias Blockly.utils.object.deepMerge
 */
 export function deepMerge(
@@ -76,8 +80,9 @@ export function deepMerge(

 /**
 * Returns an array of a given object's own enumerable property values.
+ *
 * @param obj Object containing values.
- * @return Array of values.
+ * @returns Array of values.
 * @alias Blockly.utils.object.values
 */
 export function values(obj: AnyDuringMigration): AnyDuringMigration[] {
--- a/core/utils/parsing.ts
+++ b/core/utils/parsing.ts
@@ -18,11 +18,12 @@ import * as colourUtils from './colour.js';
 /**
 * Internal implementation of the message reference and interpolation token
 * parsing used by tokenizeInterpolation() and replaceMessageReferences().
+ *
 * @param message Text which might contain string table references and
 *     interpolation tokens.
 * @param parseInterpolationTokens Option to parse numeric
 *     interpolation tokens (%1, %2, ...) when true.
- * @return Array of strings and numbers.
+ * @returns Array of strings and numbers.
 */
 function tokenizeInterpolationInternal(
    message: string, parseInterpolationTokens: boolean): (string|number)[] {
@@ -162,9 +163,10 @@ function tokenizeInterpolationInternal(
 * %{BKY_MY_MSG} will both be replaced with the value in
 * Msg['MY_MSG']). Percentage sign characters '%' may be self-escaped
 * (e.g., '%%').
+ *
 * @param message Text which might contain string table references and
 *     interpolation tokens.
- * @return Array of strings and numbers.
+ * @returns Array of strings and numbers.
 * @alias Blockly.utils.parsing.tokenizeInterpolation
 */
 export function tokenizeInterpolation(message: string): (string|number)[] {
@@ -175,9 +177,10 @@ export function tokenizeInterpolation(message: string): (string|number)[] {
 * Replaces string table references in a message, if the message is a string.
 * For example, "%{bky_my_msg}" and "%{BKY_MY_MSG}" will both be replaced with
 * the value in Msg['MY_MSG'].
+ *
 * @param message Message, which may be a string that contains
 *     string table references.
- * @return String with message references replaced.
+ * @returns String with message references replaced.
 * @alias Blockly.utils.parsing.replaceMessageReferences
 */
 export function replaceMessageReferences(message: string|
@@ -194,8 +197,9 @@ export function replaceMessageReferences(message: string|
 /**
 * Validates that any %{MSG_KEY} references in the message refer to keys of
 * the Msg string table.
+ *
 * @param message Text which might contain string table references.
- * @return True if all message references have matching values.
+ * @returns True if all message references have matching values.
 *     Otherwise, false.
 * @alias Blockly.utils.parsing.checkMessageReferences
 */
@@ -222,9 +226,10 @@ export function checkMessageReferences(message: string): boolean {
 /**
 * Parse a block colour from a number or string, as provided in a block
 * definition.
+ *
 * @param colour HSV hue value (0 to 360), #RRGGBB string,
 *     or a message reference string pointing to one of those two values.
- * @return An object containing the colour as
+ * @returns An object containing the colour as
 *     a #RRGGBB string, and the hue if the input was an HSV hue value.
 * @throws {Error} If the colour cannot be parsed.
 * @alias Blockly.utils.parsing.parseBlockColour
--- a/core/utils/rect.ts
+++ b/core/utils/rect.ts
@@ -8,6 +8,7 @@
 * Utility methods for rectangle manipulation.
 * These methods are not specific to Blockly, and could be factored out into
 * a JavaScript framework such as Closure.
+ *
 * @class
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -16,6 +17,7 @@ goog.declareModuleId('Blockly.utils.Rect');

 /**
 * Class for representing rectangular regions.
+ *
 * @alias Blockly.utils.Rect
 */
 export class Rect {
@@ -35,7 +37,7 @@ export class Rect {
   *
   * @param x The x coordinate to test for containment.
   * @param y The y coordinate to test for containment.
-   * @return Whether this rectangle contains given coordinate.
+   * @returns Whether this rectangle contains given coordinate.
   */
  contains(x: number, y: number): boolean {
    return x >= this.left && x <= this.right && y >= this.top &&
@@ -45,8 +47,9 @@ export class Rect {
  /**
   * Tests whether this rectangle intersects the provided rectangle.
   * Assumes that the coordinate system increases going down and left.
+   *
   * @param other The other rectangle to check for intersection with.
-   * @return Whether this rectangle intersects the provided rectangle.
+   * @returns Whether this rectangle intersects the provided rectangle.
   */
  intersects(other: Rect): boolean {
    return !(
--- a/core/utils/size.ts
+++ b/core/utils/size.ts
@@ -8,6 +8,7 @@
 * Utility methods for size calculation.
 * These methods are not specific to Blockly, and could be factored out into
 * a JavaScript framework such as Closure.
+ *
 * @class
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -16,6 +17,7 @@ goog.declareModuleId('Blockly.utils.Size');

 /**
 * Class for representing sizes consisting of a width and height.
+ *
 * @alias Blockly.utils.Size
 */
 export class Size {
@@ -28,9 +30,10 @@ export class Size {

  /**
   * Compares sizes for equality.
+   *
   * @param a A Size.
   * @param b A Size.
-   * @return True iff the sizes have equal widths and equal heights, or if both
+   * @returns True iff the sizes have equal widths and equal heights, or if both
   *     are null.
   */
  static equals(a: Size|null, b: Size|null): boolean {
--- a/core/utils/string.ts
+++ b/core/utils/string.ts
@@ -8,6 +8,7 @@
 * Utility methods for string manipulation.
 * These methods are not specific to Blockly, and could be factored out into
 * a JavaScript framework such as Closure.
+ *
 * @namespace Blockly.utils.string
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -19,9 +20,10 @@ import * as deprecation from './deprecation.js';
 /**
 * Fast prefix-checker.
 * Copied from Closure's goog.string.startsWith.
+ *
 * @param str The string to check.
 * @param prefix A string to look for at the start of `str`.
- * @return True if `str` begins with `prefix`.
+ * @returns True if `str` begins with `prefix`.
 * @alias Blockly.utils.string.startsWith
 * @deprecated April 2022. Use built-in string.startsWith.
 */
@@ -34,8 +36,9 @@ export function startsWith(str: string, prefix: string): boolean {

 /**
 * Given an array of strings, return the length of the shortest one.
+ *
 * @param array Array of strings.
- * @return Length of shortest string.
+ * @returns Length of shortest string.
 * @alias Blockly.utils.string.shortestStringLength
 */
 export function shortestStringLength(array: string[]): number {
@@ -52,9 +55,10 @@ export function shortestStringLength(array: string[]): number {
 /**
 * Given an array of strings, return the length of the common prefix.
 * Words may not be split.  Any space after a word is included in the length.
+ *
 * @param array Array of strings.
 * @param opt_shortest Length of shortest string.
- * @return Length of common prefix.
+ * @returns Length of common prefix.
 * @alias Blockly.utils.string.commonWordPrefix
 */
 export function commonWordPrefix(
@@ -90,9 +94,10 @@ export function commonWordPrefix(
 /**
 * Given an array of strings, return the length of the common suffix.
 * Words may not be split.  Any space after a word is included in the length.
+ *
 * @param array Array of strings.
 * @param opt_shortest Length of shortest string.
- * @return Length of common suffix.
+ * @returns Length of common suffix.
 * @alias Blockly.utils.string.commonWordSuffix
 */
 export function commonWordSuffix(
@@ -127,9 +132,10 @@ export function commonWordSuffix(

 /**
 * Wrap text to the specified width.
+ *
 * @param text Text to wrap.
 * @param limit Width to wrap each line.
- * @return Wrapped text.
+ * @returns Wrapped text.
 * @alias Blockly.utils.string.wrap
 */
 export function wrap(text: string, limit: number): string {
@@ -142,9 +148,10 @@ export function wrap(text: string, limit: number): string {

 /**
 * Wrap single line of text to the specified width.
+ *
 * @param text Text to wrap.
 * @param limit Width to wrap each line.
- * @return Wrapped text.
+ * @returns Wrapped text.
 */
 function wrapLine(text: string, limit: number): string {
  if (text.length <= limit) {
@@ -191,10 +198,11 @@ function wrapLine(text: string, limit: number): string {

 /**
 * Compute a score for how good the wrapping is.
+ *
 * @param words Array of each word.
 * @param wordBreaks Array of line breaks.
 * @param limit Width to wrap each line.
- * @return Larger the better.
+ * @returns Larger the better.
 */
 function wrapScore(
    words: string[], wordBreaks: boolean[], limit: number): number {
@@ -243,10 +251,11 @@ function wrapScore(
 /**
 * Mutate the array of line break locations until an optimal solution is found.
 * No line breaks are added or deleted, they are simply moved around.
+ *
 * @param words Array of each word.
 * @param wordBreaks Array of line breaks.
 * @param limit Width to wrap each line.
- * @return New array of optimal line breaks.
+ * @returns New array of optimal line breaks.
 */
 function wrapMutate(
    words: string[], wordBreaks: boolean[], limit: number): boolean[] {
@@ -276,9 +285,10 @@ function wrapMutate(

 /**
 * Reassemble the array of words into text, with the specified line breaks.
+ *
 * @param words Array of each word.
 * @param wordBreaks Array of line breaks.
- * @return Plain text.
+ * @returns Plain text.
 */
 function wrapToText(words: string[], wordBreaks: boolean[]): string {
  const text = [];
@@ -293,8 +303,9 @@ function wrapToText(words: string[], wordBreaks: boolean[]): string {

 /**
 * Is the given string a number (includes negative and decimals).
+ *
 * @param str Input string.
- * @return True if number, false otherwise.
+ * @returns True if number, false otherwise.
 * @alias Blockly.utils.string.isNumber
 */
 export function isNumber(str: string): boolean {
--- a/core/utils/style.ts
+++ b/core/utils/style.ts
@@ -8,6 +8,7 @@
 * Utilities for element styles.
 * These methods are not specific to Blockly, and could be factored out into
 * a JavaScript framework such as Closure.
+ *
 * @namespace Blockly.utils.style
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -21,8 +22,9 @@ import {Size} from './size.js';
 /**
 * Gets the height and width of an element.
 * Similar to Closure's goog.style.getSize
+ *
 * @param element Element to get size of.
- * @return Object with width/height properties.
+ * @returns Object with width/height properties.
 * @alias Blockly.utils.style.getSize
 */
 export function getSize(element: Element): Size {
@@ -31,6 +33,8 @@ export function getSize(element: Element): Size {

 /**
 * Private version of getSize for stubbing in tests.
+ *
+ * @param element
 */
 function getSizeInternal(element: Element): Size {
  if (getStyle(element, 'display') !== 'none') {
@@ -61,8 +65,9 @@ function getSizeInternal(element: Element): Size {

 /**
 * Gets the height and width of an element when the display is not none.
+ *
 * @param element Element to get size of.
- * @return Object with width/height properties.
+ * @returns Object with width/height properties.
 */
 function getSizeWithDisplay(element: Element): Size {
  const offsetWidth = (element as HTMLElement).offsetWidth;
@@ -81,7 +86,7 @@ function getSizeWithDisplay(element: Element): Size {
 *
 * @param element Element to get style of.
 * @param style Property to get (must be camelCase, not CSS-style).
- * @return Style value.
+ * @returns Style value.
 */
 function getStyle(element: Element, style: string): string {
  // AnyDuringMigration because:  Property 'style' does not exist on type
@@ -102,7 +107,7 @@ function getStyle(element: Element, style: string): string {
 *
 * @param element Element to get style of.
 * @param property Property to get (camel-case).
- * @return Style value.
+ * @returns Style value.
 * @alias Blockly.utils.style.getComputedStyle
 */
 export function getComputedStyle(element: Element, property: string): string {
@@ -127,7 +132,7 @@ export function getComputedStyle(element: Element, property: string): string {
 *
 * @param element Element to get style of.
 * @param style Property to get (camel-case).
- * @return Style value.
+ * @returns Style value.
 * @alias Blockly.utils.style.getCascadedStyle
 */
 export function getCascadedStyle(element: Element, style: string): string {
@@ -142,8 +147,9 @@ export function getCascadedStyle(element: Element, style: string): string {
 /**
 * Returns a Coordinate object relative to the top-left of the HTML document.
 * Similar to Closure's goog.style.getPageOffset
+ *
 * @param el Element to get the page offset for.
- * @return The page offset.
+ * @returns The page offset.
 * @alias Blockly.utils.style.getPageOffset
 */
 export function getPageOffset(el: Element): Coordinate {
@@ -165,7 +171,8 @@ export function getPageOffset(el: Element): Coordinate {
 /**
 * Calculates the viewport coordinates relative to the document.
 * Similar to Closure's goog.style.getViewportPageOffset
- * @return The page offset of the viewport.
+ *
+ * @returns The page offset of the viewport.
 * @alias Blockly.utils.style.getViewportPageOffset
 */
 export function getViewportPageOffset(): Coordinate {
@@ -200,7 +207,7 @@ export function setElementShown(el: Element, isShown: AnyDuringMigration) {
 * Copied from Closure's goog.style.isRightToLeft
 *
 * @param el The element to test.
- * @return True for right to left, false for left to right.
+ * @returns True for right to left, false for left to right.
 * @alias Blockly.utils.style.isRightToLeft
 */
 export function isRightToLeft(el: Element): boolean {
@@ -210,8 +217,9 @@ export function isRightToLeft(el: Element): boolean {
 /**
 * Gets the computed border widths (on all sides) in pixels
 * Copied from Closure's goog.style.getBorderBox
+ *
 * @param element  The element to get the border widths for.
- * @return The computed border widths.
+ * @returns The computed border widths.
 * @alias Blockly.utils.style.getBorderBox
 */
 export function getBorderBox(element: Element): Rect {
@@ -256,7 +264,7 @@ export function scrollIntoContainerView(
 *     scroll element will be used.
 * @param opt_center Whether to center the element in the container.
 *     Defaults to false.
- * @return The new scroll position of the container.
+ * @returns The new scroll position of the container.
 * @alias Blockly.utils.style.getContainerOffsetToScrollInto
 */
 export function getContainerOffsetToScrollInto(
--- a/core/utils/svg.ts
+++ b/core/utils/svg.ts
@@ -7,6 +7,7 @@
 /**
 * Defines the Svg class. Its constants enumerate
 * all SVG tag names used by Blockly.
+ *
 * @class
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -15,6 +16,7 @@ goog.declareModuleId('Blockly.utils.Svg');

 /**
 * A name with the type of the SVG element stored in the generic.
+ *
 * @alias Blockly.utils.Svg
 */
 export class Svg<_T> {
@@ -75,7 +77,8 @@ export class Svg<_T> {

  /**
   * Returns the SVG element tag name.
-   * @return The name.
+   *
+   * @returns The name.
   */
  toString(): string {
    return this.tagName;
--- a/core/utils/svg_math.ts
+++ b/core/utils/svg_math.ts
@@ -6,6 +6,7 @@

 /**
 * Utility methods realted to figuring out positions of SVG elements.
+ *
 * @namespace Blockly.utils.svgMath
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -41,8 +42,9 @@ const XY_STYLE_REGEX: RegExp =
 /**
 * Return the coordinates of the top-left corner of this element relative to
 * its parent.  Only for SVG elements and children (e.g. rect, g, path).
+ *
 * @param element SVG element to find the coordinates of.
- * @return Object with .x and .y properties.
+ * @returns Object with .x and .y properties.
 * @alias Blockly.utils.svgMath.getRelativeXY
 */
 export function getRelativeXY(element: Element): Coordinate {
@@ -86,9 +88,10 @@ export function getRelativeXY(element: Element): Coordinate {
 /**
 * Return the coordinates of the top-left corner of this element relative to
 * the div Blockly was injected into.
+ *
 * @param element SVG element to find the coordinates of. If this is not a child
 *     of the div Blockly was injected into, the behaviour is undefined.
- * @return Object with .x and .y properties.
+ * @returns Object with .x and .y properties.
 * @alias Blockly.utils.svgMath.getInjectionDivXY
 */
 export function getInjectionDivXY(element: Element): Coordinate {
@@ -110,7 +113,8 @@ export function getInjectionDivXY(element: Element): Coordinate {
 /**
 * Check if 3D transforms are supported by adding an element
 * and attempting to set the property.
- * @return True if 3D transforms are supported.
+ *
+ * @returns True if 3D transforms are supported.
 * @alias Blockly.utils.svgMath.is3dSupported
 */
 export function is3dSupported(): boolean {
@@ -170,7 +174,8 @@ export function is3dSupported(): boolean {
 /**
 * Get the position of the current viewport in window coordinates.  This takes
 * scroll into account.
- * @return An object containing window width, height, and scroll position in
+ *
+ * @returns An object containing window width, height, and scroll position in
 *     window coordinates.
 * @alias Blockly.utils.svgMath.getViewportBBox
 * @internal
@@ -186,7 +191,8 @@ export function getViewportBBox(): Rect {
 /**
 * Gets the document scroll distance as a coordinate object.
 * Copied from Closure's goog.dom.getDocumentScroll.
- * @return Object with values 'x' and 'y'.
+ *
+ * @returns Object with values 'x' and 'y'.
 * @alias Blockly.utils.svgMath.getDocumentScroll
 */
 export function getDocumentScroll(): Coordinate {
@@ -204,10 +210,11 @@ export function getDocumentScroll(): Coordinate {

 /**
 * Converts screen coordinates to workspace coordinates.
+ *
 * @param ws The workspace to find the coordinates on.
 * @param screenCoordinates The screen coordinates to be converted to workspace
 *     coordinates
- * @return The workspace coordinates.
+ * @returns The workspace coordinates.
 * @alias Blockly.utils.svgMath.screenToWsCoordinates
 */
 export function screenToWsCoordinates(
@@ -240,8 +247,9 @@ export function screenToWsCoordinates(

 /**
 * Returns the dimensions of the specified SVG image.
+ *
 * @param svg SVG image.
- * @return Contains width and height properties.
+ * @returns Contains width and height properties.
 * @deprecated Use workspace.getCachedParentSvgSize. (2021 March 5)
 * @alias Blockly.utils.svgMath.svgSize
 */
--- a/core/utils/svg_paths.ts
+++ b/core/utils/svg_paths.ts
@@ -6,6 +6,7 @@

 /**
 * Methods for creating parts of SVG path strings.  See
+ *
 * @namespace Blockly.utils.svgPaths
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -17,9 +18,10 @@ goog.declareModuleId('Blockly.utils.svgPaths');
 * the coordinate is relative or absolute.  The result has leading
 * and trailing spaces, and separates the x and y coordinates with a comma but
 * no space.
+ *
 * @param x The x coordinate.
 * @param y The y coordinate.
- * @return A string of the format ' x,y '
+ * @returns A string of the format ' x,y '
 * @alias Blockly.utils.svgPaths.point
 */
 export function point(x: number, y: number): string {
@@ -30,12 +32,13 @@ export function point(x: number, y: number): string {
 * Draw a cubic or quadratic curve.  See
 * developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#Cubic_B%C3%A9zier_Curve
 * These coordinates are unitless and hence in the user coordinate system.
+ *
 * @param command The command to use.
 *     Should be one of: c, C, s, S, q, Q.
 * @param points  An array containing all of the points to pass to the curve
 *     command, in order.  The points are represented as strings of the format '
 *     x, y '.
- * @return A string defining one or more Bezier curves.  See the MDN
+ * @returns A string defining one or more Bezier curves.  See the MDN
 *     documentation for exact format.
 * @alias Blockly.utils.svgPaths.curve
 */
@@ -48,9 +51,10 @@ export function curve(command: string, points: string[]): string {
 * The coordinates are absolute.
 * These coordinates are unitless and hence in the user coordinate system.
 * See developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths#Line_commands
+ *
 * @param x The absolute x coordinate.
 * @param y The absolute y coordinate.
- * @return A string of the format ' M x,y '
+ * @returns A string of the format ' M x,y '
 * @alias Blockly.utils.svgPaths.moveTo
 */
 export function moveTo(x: number, y: number): string {
@@ -62,9 +66,10 @@ export function moveTo(x: number, y: number): string {
 * Coordinates are relative.
 * These coordinates are unitless and hence in the user coordinate system.
 * See developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths#Line_commands
+ *
 * @param dx The relative x coordinate.
 * @param dy The relative y coordinate.
- * @return A string of the format ' m dx,dy '
+ * @returns A string of the format ' m dx,dy '
 * @alias Blockly.utils.svgPaths.moveBy
 */
 export function moveBy(dx: number, dy: number): string {
@@ -76,9 +81,10 @@ export function moveBy(dx: number, dy: number): string {
 * point shifted by dx along the x-axis and dy along the y-axis.
 * These coordinates are unitless and hence in the user coordinate system.
 * See developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths#Line_commands
+ *
 * @param dx The relative x coordinate.
 * @param dy The relative y coordinate.
- * @return A string of the format ' l dx,dy '
+ * @returns A string of the format ' l dx,dy '
 * @alias Blockly.utils.svgPaths.lineTo
 */
 export function lineTo(dx: number, dy: number): string {
@@ -90,9 +96,10 @@ export function lineTo(dx: number, dy: number): string {
 * equivalent to a series of 'l' commands.
 * These coordinates are unitless and hence in the user coordinate system.
 * See developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths#Line_commands
+ *
 * @param points An array containing all of the points to draw lines to, in
 *     order.  The points are represented as strings of the format ' dx,dy '.
- * @return A string of the format ' l (dx,dy)+ '
+ * @returns A string of the format ' l (dx,dy)+ '
 * @alias Blockly.utils.svgPaths.line
 */
 export function line(points: string[]): string {
@@ -105,11 +112,12 @@ export function line(points: string[]): string {
 * relative or absolute.
 * These coordinates are unitless and hence in the user coordinate system.
 * See developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#LineTo_path_commands
+ *
 * @param command The command to prepend to the coordinate.  This should be one
 *     of: V, v, H, h.
 * @param val The coordinate to pass to the command.  It may be absolute or
 *     relative.
- * @return A string of the format ' command val '
+ * @returns A string of the format ' command val '
 * @alias Blockly.utils.svgPaths.lineOnAxis
 */
 export function lineOnAxis(command: string, val: number): string {
@@ -120,13 +128,14 @@ export function lineOnAxis(command: string, val: number): string {
 * Draw an elliptical arc curve.
 * These coordinates are unitless and hence in the user coordinate system.
 * See developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#Elliptical_Arc_Curve
+ *
 * @param command The command string.  Either 'a' or 'A'.
 * @param flags The flag string.  See the MDN documentation for a description
 *     and examples.
 * @param radius The radius of the arc to draw.
 * @param point The point to move the cursor to after drawing the arc, specified
 *     either in absolute or relative coordinates depending on the command.
- * @return A string of the format 'command radius radius flags point'
+ * @returns A string of the format 'command radius radius flags point'
 * @alias Blockly.utils.svgPaths.arc
 */
 export function arc(
--- a/core/utils/toolbox.ts
+++ b/core/utils/toolbox.ts
@@ -6,6 +6,7 @@

 /**
 * Utility functions for the toolbox and flyout.
+ *
 * @namespace Blockly.utils.toolbox
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -28,6 +29,7 @@ import * as userAgent from './useragent.js';
 /**
 * The information needed to create a block in the toolbox.
 * Note that disabled has a different type for backwards compatibility.
+ *
 * @alias Blockly.utils.toolbox.BlockInfo
 */
 export interface BlockInfo {
@@ -52,6 +54,7 @@ export interface BlockInfo {

 /**
 * The information needed to create a separator in the toolbox.
+ *
 * @alias Blockly.utils.toolbox.SeparatorInfo
 */
 export interface SeparatorInfo {
@@ -63,6 +66,7 @@ export interface SeparatorInfo {

 /**
 * The information needed to create a button in the toolbox.
+ *
 * @alias Blockly.utils.toolbox.ButtonInfo
 */
 export interface ButtonInfo {
@@ -73,6 +77,7 @@ export interface ButtonInfo {

 /**
 * The information needed to create a label in the toolbox.
+ *
 * @alias Blockly.utils.toolbox.LabelInfo
 */
 export interface LabelInfo {
@@ -83,12 +88,14 @@ export interface LabelInfo {

 /**
 * The information needed to create either a button or a label in the flyout.
+ *
 * @alias Blockly.utils.toolbox.ButtonOrLabelInfo
 */
 export type ButtonOrLabelInfo = ButtonInfo|LabelInfo;

 /**
 * The information needed to create a category in the toolbox.
+ *
 * @alias Blockly.utils.toolbox.StaticCategoryInfo
 */
 export interface StaticCategoryInfo {
@@ -104,6 +111,7 @@ export interface StaticCategoryInfo {

 /**
 * The information needed to create a custom category.
+ *
 * @alias Blockly.utils.toolbox.DynamicCategoryInfo
 */
 export interface DynamicCategoryInfo {
@@ -118,18 +126,21 @@ export interface DynamicCategoryInfo {

 /**
 * The information needed to create either a dynamic or static category.
+ *
 * @alias Blockly.utils.toolbox.CategoryInfo
 */
 export type CategoryInfo = StaticCategoryInfo|DynamicCategoryInfo;

 /**
 * Any information that can be used to create an item in the toolbox.
+ *
 * @alias Blockly.utils.toolbox.ToolboxItemInfo
 */
 export type ToolboxItemInfo = FlyoutItemInfo|StaticCategoryInfo;

 /**
 * All the different types that can be displayed in a flyout.
+ *
 * @alias Blockly.utils.toolbox.FlyoutItemInfo
 */
 export type FlyoutItemInfo =
@@ -137,6 +148,7 @@ export type FlyoutItemInfo =

 /**
 * The JSON definition of a toolbox.
+ *
 * @alias Blockly.utils.toolbox.ToolboxInfo
 */
 export interface ToolboxInfo {
@@ -146,18 +158,21 @@ export interface ToolboxInfo {

 /**
 * An array holding flyout items.
+ *
 * @alias Blockly.utils.toolbox.FlyoutItemInfoArray
 */
 export type FlyoutItemInfoArray = FlyoutItemInfo[];

 /**
 * All of the different types that can create a toolbox.
+ *
 * @alias Blockly.utils.toolbox.ToolboxDefinition
 */
 export type ToolboxDefinition = Node|ToolboxInfo|string;

 /**
 * All of the different types that can be used to show items in a flyout.
+ *
 * @alias Blockly.utils.toolbox.FlyoutDefinition
 */
 export type FlyoutDefinition = FlyoutItemInfoArray|NodeList|ToolboxInfo|Node[];
@@ -178,6 +193,7 @@ const FLYOUT_TOOLBOX_KIND = 'flyoutToolbox';

 /**
 * Position of the toolbox and/or flyout relative to the workspace.
+ *
 * @alias Blockly.utils.toolbox.Position
 */
 export enum Position {
@@ -189,8 +205,9 @@ export enum Position {

 /**
 * Converts the toolbox definition into toolbox JSON.
+ *
 * @param toolboxDef The definition of the toolbox in one of its many forms.
- * @return Object holding information for creating a toolbox.
+ * @returns Object holding information for creating a toolbox.
 * @alias Blockly.utils.toolbox.convertToolboxDefToJson
 * @internal
 */
@@ -214,6 +231,7 @@ export function convertToolboxDefToJson(toolboxDef: ToolboxDefinition|

 /**
 * Validates the toolbox JSON fields have been set correctly.
+ *
 * @param toolboxJson Object holding information for creating a toolbox.
 * @throws {Error} if the toolbox is not the correct format.
 */
@@ -237,8 +255,9 @@ function validateToolbox(toolboxJson: ToolboxInfo) {

 /**
 * Converts the flyout definition into a list of flyout items.
+ *
 * @param flyoutDef The definition of the flyout in one of its many forms.
- * @return A list of flyout items.
+ * @returns A list of flyout items.
 * @alias Blockly.utils.toolbox.convertFlyoutDefToJsonArray
 * @internal
 */
@@ -268,8 +287,9 @@ export function convertFlyoutDefToJsonArray(flyoutDef: FlyoutDefinition|

 /**
 * Whether or not the toolbox definition has categories.
+ *
 * @param toolboxJson Object holding information for creating a toolbox.
- * @return True if the toolbox has categories.
+ * @returns True if the toolbox has categories.
 * @alias Blockly.utils.toolbox.hasCategories
 * @internal
 */
@@ -279,6 +299,8 @@ export function hasCategories(toolboxJson: ToolboxInfo|null): boolean {

 /**
 * Private version of hasCategories for stubbing in tests.
+ *
+ * @param toolboxJson
 */
 function hasCategoriesInternal(toolboxJson: ToolboxInfo|null): boolean {
  if (!toolboxJson) {
@@ -298,8 +320,9 @@ function hasCategoriesInternal(toolboxJson: ToolboxInfo|null): boolean {

 /**
 * Whether or not the category is collapsible.
+ *
 * @param categoryInfo Object holing information for creating a category.
- * @return True if the category has subcategories.
+ * @returns True if the category has subcategories.
 * @alias Blockly.utils.toolbox.isCategoryCollapsible
 * @internal
 */
@@ -318,8 +341,9 @@ export function isCategoryCollapsible(categoryInfo: CategoryInfo): boolean {

 /**
 * Parses the provided toolbox definition into a consistent format.
+ *
 * @param toolboxDef The definition of the toolbox in one of its many forms.
- * @return Object holding information for creating a toolbox.
+ * @returns Object holding information for creating a toolbox.
 */
 function convertToToolboxJson(toolboxDef: Node): ToolboxInfo {
  const contents = xmlToJsonArray(toolboxDef as Node | Node[]);
@@ -332,8 +356,9 @@ function convertToToolboxJson(toolboxDef: Node): ToolboxInfo {

 /**
 * Converts the xml for a toolbox to JSON.
+ *
 * @param toolboxDef The definition of the toolbox in one of its many forms.
- * @return A list of objects in the toolbox.
+ * @returns A list of objects in the toolbox.
 */
 function xmlToJsonArray(toolboxDef: Node|Node[]|NodeList): FlyoutItemInfoArray|
    ToolboxItemInfo[] {
@@ -373,6 +398,7 @@ function xmlToJsonArray(toolboxDef: Node|Node[]|NodeList): FlyoutItemInfoArray|

 /**
 * Adds the attributes on the node to the given object.
+ *
 * @param node The node to copy the attributes from.
 * @param obj The object to copy the attributes to.
 */
@@ -394,8 +420,9 @@ function addAttributes(node: Node, obj: AnyDuringMigration) {

 /**
 * Parse the provided toolbox tree into a consistent DOM format.
+ *
 * @param toolboxDef DOM tree of blocks, or text representation of same.
- * @return DOM tree of blocks, or null.
+ * @returns DOM tree of blocks, or null.
 * @alias Blockly.utils.toolbox.parseToolboxTree
 */
 export function parseToolboxTree(toolboxDef: Element|null|string): Element|
--- a/core/utils/useragent.ts
+++ b/core/utils/useragent.ts
@@ -8,6 +8,7 @@
 * Useragent detection.
 * These methods are not specific to Blockly, and could be factored out into
 * a JavaScript framework such as Closure.
+ *
 * @namespace Blockly.utils.userAgent
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -48,8 +49,9 @@ rawUserAgent = raw;
 const rawUpper = rawUserAgent.toUpperCase();
 /**
 * Case-insensitive test of whether name is in the useragent string.
+ *
 * @param name Name to test.
- * @return True if name is present.
+ * @returns True if name is present.
 */
 function has(name: string): boolean {
  return rawUpper.indexOf(name.toUpperCase()) !== -1;
--- a/core/utils/xml.ts
+++ b/core/utils/xml.ts
@@ -8,6 +8,7 @@
 * XML element manipulation.
 * These methods are not specific to Blockly, and could be factored out into
 * a JavaScript framework such as Closure.
+ *
 * @namespace Blockly.utils.xml
 */
 import * as goog from '../../closure/goog/goog.js';
@@ -16,6 +17,7 @@ goog.declareModuleId('Blockly.utils.xml');

 /**
 * Namespace for Blockly's XML.
+ *
 * @alias Blockly.utils.xml.NAME_SPACE
 */
 export const NAME_SPACE = 'https://developers.google.com/blockly/xml';
@@ -30,7 +32,8 @@ let xmlDocument: Document = globalThis['document'];

 /**
 * Get the document object to use for XML serialization.
- * @return The document object.
+ *
+ * @returns The document object.
 * @alias Blockly.utils.xml.getDocument
 */
 export function getDocument(): Document {
@@ -39,6 +42,7 @@ export function getDocument(): Document {

 /**
 * Get the document object to use for XML serialization.
+ *
 * @param document The document object to use.
 * @alias Blockly.utils.xml.setDocument
 */
@@ -48,8 +52,9 @@ export function setDocument(document: Document) {

 /**
 * Create DOM element for XML.
+ *
 * @param tagName Name of DOM element.
- * @return New DOM element.
+ * @returns New DOM element.
 * @alias Blockly.utils.xml.createElement
 */
 export function createElement(tagName: string): Element {
@@ -58,8 +63,9 @@ export function createElement(tagName: string): Element {

 /**
 * Create text element for XML.
+ *
 * @param text Text content.
- * @return New DOM text node.
+ * @returns New DOM text node.
 * @alias Blockly.utils.xml.createTextNode
 */
 export function createTextNode(text: string): Text {
@@ -68,8 +74,9 @@ export function createTextNode(text: string): Text {

 /**
 * Converts an XML string into a DOM tree.
+ *
 * @param text XML string.
- * @return The DOM document.
+ * @returns The DOM document.
 * @throws if XML doesn't parse.
 * @alias Blockly.utils.xml.textToDomDocument
 */
@@ -81,8 +88,9 @@ export function textToDomDocument(text: string): Document {
 /**
 * Converts a DOM structure into plain text.
 * Currently the text format is fairly ugly: all one line with no whitespace.
+ *
 * @param dom A tree of XML nodes.
- * @return Text representation.
+ * @returns Text representation.
 * @alias Blockly.utils.xml.domToText
 */
 export function domToText(dom: Node): string {