diff --git a/core/browser_events.js b/core/browser_events.js index 4a7b03601..3a251637b 100644 --- a/core/browser_events.js +++ b/core/browser_events.js @@ -31,7 +31,7 @@ Blockly.browserEvents.Data; * mousedown or mousemove, which may be part of a drag or click). * @param {!EventTarget} node Node upon which to listen. * @param {string} name Event name to listen to (e.g. 'mousedown'). - * @param {Object} thisObject The value of 'this' in the function. + * @param {?Object} thisObject The value of 'this' in the function. * @param {!Function} func Function to call when event is triggered. * @param {boolean=} opt_noCaptureIdentifier True if triggering on this event * should not block execution of other event handlers on this touch or @@ -106,7 +106,7 @@ Blockly.browserEvents.conditionalBind = function( * mouseover for tooltips). * @param {!EventTarget} node Node upon which to listen. * @param {string} name Event name to listen to (e.g. 'mousedown'). - * @param {Object} thisObject The value of 'this' in the function. + * @param {?Object} thisObject The value of 'this' in the function. * @param {!Function} func Function to call when event is triggered. * @return {!Blockly.browserEvents.Data} Opaque data that can be passed to * unbindEvent_. diff --git a/core/generator.js b/core/generator.js index f06682271..7af52afaa 100644 --- a/core/generator.js +++ b/core/generator.js @@ -16,6 +16,7 @@ goog.provide('Blockly.Generator'); goog.require('Blockly.Block'); /** @suppress {extraRequire} */ goog.require('Blockly.constants'); +goog.require('Blockly.utils.deprecation'); goog.requireType('Blockly.Names'); goog.requireType('Blockly.Workspace'); @@ -408,20 +409,22 @@ Object.defineProperty(Blockly.Generator.prototype, 'variableDB_', { * Getter. * @deprecated 'variableDB_' was renamed to 'nameDB_' (May 2021). * @this {Blockly.Generator} - * @return {Blockly.Names} Name database. + * @return {!Blockly.Names|undefined} Name database. */ get: function() { - console.warn('Deprecated use of "variableDB_"; change to "nameDB_"'); + Blockly.utils.deprecation.warn( + 'variableDB_', 'May 2021', 'May 2026', 'nameDB_'); return this.nameDB_; }, /** * Setter. * @deprecated 'variableDB_' was renamed to 'nameDB_' (May 2021). * @this {Blockly.Generator} - * @param {Blockly.Names} nameDb New name database. + * @param {!Blockly.Names|undefined} nameDb New name database. */ set: function(nameDb) { - console.warn('Deprecated use of "variableDB_"; change to "nameDB_"'); + Blockly.utils.deprecation.warn( + 'variableDB_', 'May 2021', 'May 2026', 'nameDB_'); this.nameDB_ = nameDb; } }); diff --git a/core/utils.js b/core/utils.js index ddff23028..171e83422 100644 --- a/core/utils.js +++ b/core/utils.js @@ -164,7 +164,7 @@ Blockly.utils.isRightButton = function(e) { * The origin (0,0) is the top-left corner of the Blockly SVG. * @param {!Event} e Mouse event. * @param {!Element} svg SVG element. - * @param {SVGMatrix} matrix Inverted screen CTM to use. + * @param {?SVGMatrix} matrix Inverted screen CTM to use. * @return {!SVGPoint} Object with .x and .y properties. */ Blockly.utils.mouseToSvg = function(e, svg, matrix) { @@ -583,10 +583,10 @@ Blockly.utils.getBlockTypeCounts = function(block, opt_stripFollowing) { /** * Converts screen coordinates to workspace coordinates. - * @param {Blockly.WorkspaceSvg} ws The workspace to find the coordinates on. - * @param {Blockly.utils.Coordinate} screenCoordinates The screen coordinates to + * @param {!Blockly.WorkspaceSvg} ws The workspace to find the coordinates on. + * @param {!Blockly.utils.Coordinate} screenCoordinates The screen coordinates to * be converted to workspace coordinates - * @return {Blockly.utils.Coordinate} The workspace coordinates. + * @return {!Blockly.utils.Coordinate} The workspace coordinates. * @package */ Blockly.utils.screenToWsCoordinates = function(ws, screenCoordinates) { diff --git a/core/utils/coordinate.js b/core/utils/coordinate.js index be17d00a1..da196acea 100644 --- a/core/utils/coordinate.js +++ b/core/utils/coordinate.js @@ -42,8 +42,8 @@ Blockly.utils.Coordinate = function(x, y) { /** * Compares coordinates for equality. - * @param {Blockly.utils.Coordinate} a A Coordinate. - * @param {Blockly.utils.Coordinate} b A Coordinate. + * @param {?Blockly.utils.Coordinate} a A Coordinate. + * @param {?Blockly.utils.Coordinate} b A Coordinate. * @return {boolean} True iff the coordinates are equal, or if both are null. */ Blockly.utils.Coordinate.equals = function(a, b) { diff --git a/core/utils/deprecation.js b/core/utils/deprecation.js index 1fde59f72..4c948f22b 100644 --- a/core/utils/deprecation.js +++ b/core/utils/deprecation.js @@ -19,18 +19,19 @@ goog.provide('Blockly.utils.deprecation'); /** - * Warn developers that a function is deprecated. - * @param {string} functionName The name of the function. - * @param {string} deprecationDate The date when the function was deprecated. + * Warn developers that a function or property is deprecated. + * @param {string} name The name of the function or property. + * @param {string} deprecationDate The date of deprecation. * Prefer 'month yyyy' or 'quarter yyyy' format. - * @param {string} deletionDate The date when the function will be deleted, in - * the same format as the deprecation date. - * @param {string=} opt_use The name of a function to use instead, if any. + * @param {string} deletionDate The date of deletion, in the same format as the + * deprecation date. + * @param {string=} opt_use The name of a function or property to use instead, + * if any. * @package */ Blockly.utils.deprecation.warn = function( - functionName, deprecationDate, deletionDate, opt_use) { - var msg = functionName + ' was deprecated on ' + deprecationDate + + name, deprecationDate, deletionDate, opt_use) { + var msg = name + ' was deprecated on ' + deprecationDate + ' and will be deleted on ' + deletionDate + '.'; if (opt_use) { msg += '\nUse ' + opt_use + ' instead.'; diff --git a/core/utils/dom.js b/core/utils/dom.js index 3762297fa..9aa62807c 100644 --- a/core/utils/dom.js +++ b/core/utils/dom.js @@ -175,8 +175,8 @@ Blockly.utils.dom.hasClass = function(element, className) { /** * Removes a node from its parent. No-op if not attached to a parent. - * @param {Node} node The node to remove. - * @return {Node} The node removed if removed; else, null. + * @param {?Node} node The node to remove. + * @return {?Node} The node removed if removed; else, null. */ // Copied from Closure goog.dom.removeNode Blockly.utils.dom.removeNode = function(node) { diff --git a/core/utils/rect.js b/core/utils/rect.js index fcea05623..128ec4eae 100644 --- a/core/utils/rect.js +++ b/core/utils/rect.js @@ -56,7 +56,7 @@ Blockly.utils.Rect.prototype.contains = function(x, y) { /** * Tests whether this rectangle intersects the provided rectangle. * Assumes that the coordinate system increases going down and left. - * @param {Blockly.utils.Rect} other The other rectangle to check for + * @param {!Blockly.utils.Rect} other The other rectangle to check for * intersection with. * @return {boolean} Whether this rectangle intersects the provided rectangle. */ diff --git a/core/utils/size.js b/core/utils/size.js index 66c9d0be1..2ffa91ac1 100644 --- a/core/utils/size.js +++ b/core/utils/size.js @@ -42,8 +42,8 @@ Blockly.utils.Size = function(width, height) { /** * Compares sizes for equality. - * @param {Blockly.utils.Size} a A Size. - * @param {Blockly.utils.Size} b A Size. + * @param {?Blockly.utils.Size} a A Size. + * @param {?Blockly.utils.Size} b A Size. * @return {boolean} True iff the sizes have equal widths and equal * heights, or if both are null. */ diff --git a/core/utils/toolbox.js b/core/utils/toolbox.js index e50f3b07f..bbce2ce39 100644 --- a/core/utils/toolbox.js +++ b/core/utils/toolbox.js @@ -213,7 +213,7 @@ Blockly.utils.toolbox.convertToolboxDefToJson = function(toolboxDef) { /** * Validates the toolbox JSON fields have been set correctly. - * @param {Blockly.utils.toolbox.ToolboxInfo} toolboxJson Object holding + * @param {!Blockly.utils.toolbox.ToolboxInfo} toolboxJson Object holding * information for creating a toolbox. * @throws {Error} if the toolbox is not the correct format. * @private diff --git a/core/variables.js b/core/variables.js index ac515a6a3..f11e8e7df 100644 --- a/core/variables.js +++ b/core/variables.js @@ -322,13 +322,12 @@ Blockly.Variables.createVariable = * collision. * @param {!Blockly.Workspace} workspace The workspace on which to rename the * variable. - * @param {Blockly.VariableModel} variable Variable to rename. + * @param {!Blockly.VariableModel} variable Variable to rename. * @param {function(?string=)=} opt_callback A callback. It will * be passed an acceptable new variable name, or null if change is to be * aborted (cancel button), or undefined if an existing variable was chosen. */ -Blockly.Variables.renameVariable = function(workspace, variable, - opt_callback) { +Blockly.Variables.renameVariable = function(workspace, variable, opt_callback) { // This function needs to be named so it can be called recursively. var promptAndCheckWithAlert = function(defaultName) { var promptText = diff --git a/core/widgetdiv.js b/core/widgetdiv.js index 608048aa9..316e78b61 100644 --- a/core/widgetdiv.js +++ b/core/widgetdiv.js @@ -190,8 +190,8 @@ Blockly.WidgetDiv.positionWithAnchor = function(viewportBBox, anchorBBox, * current viewport, in window coordinates. * @param {!Blockly.utils.Rect} anchorBBox The bounding rectangle of the anchor, * in window coordinates. - * @param {Blockly.utils.Size} widgetSize The dimensions of the widget inside the - * widget div. + * @param {!Blockly.utils.Size} widgetSize The dimensions of the widget inside + * the widget div. * @param {boolean} rtl Whether the Blockly workspace is in RTL mode. * @return {number} A valid x-coordinate for the top left corner of the widget * div, in window coordinates. @@ -222,8 +222,8 @@ Blockly.WidgetDiv.calculateX_ = function(viewportBBox, anchorBBox, widgetSize, * current viewport, in window coordinates. * @param {!Blockly.utils.Rect} anchorBBox The bounding rectangle of the anchor, * in window coordinates. - * @param {Blockly.utils.Size} widgetSize The dimensions of the widget inside the - * widget div. + * @param {!Blockly.utils.Size} widgetSize The dimensions of the widget inside + * the widget div. * @return {number} A valid y-coordinate for the top left corner of the widget * div, in window coordinates. * @private diff --git a/core/workspace.js b/core/workspace.js index 9e48f29d8..82096922a 100644 --- a/core/workspace.js +++ b/core/workspace.js @@ -676,7 +676,7 @@ Blockly.Workspace.prototype.fireChangeListener = function(event) { /** * Find the block on this workspace with the specified ID. * @param {string} id ID of block to find. - * @return {Blockly.Block} The sought after block, or null if not found. + * @return {?Blockly.Block} The sought after block, or null if not found. */ Blockly.Workspace.prototype.getBlockById = function(id) { return this.blockDB_[id] || null; @@ -704,7 +704,7 @@ Blockly.Workspace.prototype.removeBlockById = function(id) { /** * Find the comment on this workspace with the specified ID. * @param {string} id ID of comment to find. - * @return {Blockly.WorkspaceComment} The sought after comment, or null if not + * @return {?Blockly.WorkspaceComment} The sought after comment, or null if not * found. * @package */ diff --git a/core/xml.js b/core/xml.js index 9a6b045e1..ad06f6783 100644 --- a/core/xml.js +++ b/core/xml.js @@ -691,7 +691,7 @@ Blockly.Xml.mapSupportedXmlTags_ = function(xmlBlock) { /** * Applies mutation tag child nodes to the given block. - * @param {Array} xmlChildren Child nodes. + * @param {!Array} xmlChildren Child nodes. * @param {!Blockly.Block} block The block to apply the child nodes on. * @return {boolean} True if mutation may have added some elements that need * initialization (requiring initSvg call). @@ -714,7 +714,7 @@ Blockly.Xml.applyMutationTagNodes_ = function(xmlChildren, block) { /** * Applies comment tag child nodes to the given block. - * @param {Array} xmlChildren Child nodes. + * @param {!Array} xmlChildren Child nodes. * @param {!Blockly.Block} block The block to apply the child nodes on. * @private */ @@ -741,7 +741,7 @@ Blockly.Xml.applyCommentTagNodes_ = function(xmlChildren, block) { /** * Applies data tag child nodes to the given block. - * @param {Array} xmlChildren Child nodes. + * @param {!Array} xmlChildren Child nodes. * @param {!Blockly.Block} block The block to apply the child nodes on. * @private */ @@ -753,7 +753,7 @@ Blockly.Xml.applyDataTagNodes_ = function(xmlChildren, block) { /** * Applies field tag child nodes to the given block. - * @param {Array} xmlChildren Child nodes. + * @param {!Array} xmlChildren Child nodes. * @param {!Blockly.Block} block The block to apply the child nodes on. * @private */ @@ -787,7 +787,7 @@ Blockly.Xml.findChildBlocks_ = function(xmlNode) { /** * Applies input child nodes (value or statement) to the given block. - * @param {Array} xmlChildren Child nodes. + * @param {!Array} xmlChildren Child nodes. * @param {!Blockly.Workspace} workspace The workspace containing the given * block. * @param {!Blockly.Block} block The block to apply the child nodes on. @@ -821,7 +821,7 @@ Blockly.Xml.applyInputTagNodes_ = function(xmlChildren, workspace, block, /** * Applies next child nodes to the given block. - * @param {Array} xmlChildren Child nodes. + * @param {!Array} xmlChildren Child nodes. * @param {!Blockly.Workspace} workspace The workspace containing the given * block. * @param {!Blockly.Block} block The block to apply the child nodes on.