Make JSDoc object nullability more strict.

Also make Blockly.utils.deprecation.warn apply to properties.

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_.

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;
   }
 });

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) {

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) {

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.';

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) {

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.
  */

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.
  */

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

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 =

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

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
  */

core/xml.js

@@ -691,7 +691,7 @@ Blockly.Xml.mapSupportedXmlTags_ = function(xmlBlock) {
 
 /**
  * Applies mutation tag child nodes to the given block.
- * @param {Array<!Element>} xmlChildren Child nodes.
+ * @param {!Array<!Element>} 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<!Element>} xmlChildren Child nodes.
+ * @param {!Array<!Element>} 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<!Element>} xmlChildren Child nodes.
+ * @param {!Array<!Element>} 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<!Element>} xmlChildren Child nodes.
+ * @param {!Array<!Element>} 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<!Element>} xmlChildren Child nodes.
+ * @param {!Array<!Element>} 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<!Element>} xmlChildren Child nodes.
+ * @param {!Array<!Element>} 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.