More JSDoc improvements

2026-03-12 16:20:12 +01:00 · 2021-05-27 13:09:50 -07:00
parent f64c11d74e
commit e661c92a36
32 changed files with 154 additions and 158 deletions
--- a/core/block.js
+++ b/core/block.js
@@ -305,10 +305,10 @@ Blockly.Block.prototype.colour_ = '#000000';

 /**
 * Name of the block style.
- * @type {?string}
+ * @type {string}
 * @protected
 */
-Blockly.Block.prototype.styleName_ = null;
+Blockly.Block.prototype.styleName_ = '';

 /**
 * An optional method called during initialization.
@@ -498,7 +498,7 @@ Blockly.Block.prototype.unplugFromRow_ = function(opt_healStack) {
 * Since only one block can be displaced and attached to the insertion marker
 * this should only ever return one connection.
 *
- * @return {Blockly.Connection} The connection on the value input, or null.
+ * @return {?Blockly.Connection} The connection on the value input, or null.
 * @private
 */
 Blockly.Block.prototype.getOnlyValueConnection_ = function() {
@@ -573,7 +573,7 @@ Blockly.Block.prototype.getConnections_ = function(_all) {

 /**
 * Walks down a stack of blocks and finds the last next connection on the stack.
- * @return {Blockly.Connection} The last next connection on the stack, or null.
+ * @return {?Blockly.Connection} The last next connection on the stack, or null.
 * @package
 */
 Blockly.Block.prototype.lastConnectionInStack = function() {
@@ -602,7 +602,7 @@ Blockly.Block.prototype.bumpNeighbours = function() {
 * Return the parent block or null if this block is at the top level. The 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 {Blockly.Block} The block that holds the current block.
+ * @return {?Blockly.Block} The block (if any) that holds the current block.
 */
 Blockly.Block.prototype.getParent = function() {
  // Look at the DOM to see if we are nested in another block.
@@ -612,7 +612,8 @@ Blockly.Block.prototype.getParent = function() {
 /**
 * Return the input that connects to the specified block.
 * @param {!Blockly.Block} block A block connected to an input on this block.
- * @return {Blockly.Input} The input that connects to the specified block.
+ * @return {?Blockly.Input} The input (if any) that connects to the specified
+ *     block.
 */
 Blockly.Block.prototype.getInputWithBlock = function(block) {
  for (var i = 0, input; (input = this.inputList[i]); i++) {
@@ -627,7 +628,7 @@ Blockly.Block.prototype.getInputWithBlock = function(block) {
 * Return the parent block that surrounds the current block, or null if this
 * 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 {Blockly.Block} The block that surrounds the current block.
+ * @return {?Blockly.Block} The block (if any) that surrounds the current block.
 */
 Blockly.Block.prototype.getSurroundParent = function() {
  var block = this;
@@ -645,7 +646,7 @@ Blockly.Block.prototype.getSurroundParent = function() {

 /**
 * Return the next statement block directly connected to this block.
- * @return {Blockly.Block} The next statement block or null.
+ * @return {?Blockly.Block} The next statement block or null.
 */
 Blockly.Block.prototype.getNextBlock = function() {
  return this.nextConnection && this.nextConnection.targetBlock();
@@ -653,7 +654,7 @@ Blockly.Block.prototype.getNextBlock = function() {

 /**
 * Returns the block connected to the previous connection.
- * @return {Blockly.Block} The previous statement block or null.
+ * @return {?Blockly.Block} The previous statement block or null.
 */
 Blockly.Block.prototype.getPreviousBlock = function() {
  return this.previousConnection && this.previousConnection.targetBlock();
@@ -662,7 +663,7 @@ Blockly.Block.prototype.getPreviousBlock = function() {
 /**
 * Return the connection on the first statement input on this block, or null if
 * there are none.
- * @return {Blockly.Connection} The first statement connection or null.
+ * @return {?Blockly.Connection} The first statement connection or null.
 * @package
 */
 Blockly.Block.prototype.getFirstStatementConnection = function() {
@@ -905,7 +906,7 @@ Blockly.Block.prototype.isDisposed = function() {
 * Used to match connections between a block and its insertion marker.
 * @param {!Blockly.Block} otherBlock The other block to match against.
 * @param {!Blockly.Connection} conn The other connection to match.
- * @return {Blockly.Connection} The matching connection on this block, or null.
+ * @return {?Blockly.Connection} The matching connection on this block, or null.
 * @package
 */
 Blockly.Block.prototype.getMatchingConnection = function(otherBlock, conn) {
@@ -959,7 +960,7 @@ Blockly.Block.prototype.getColour = function() {

 /**
 * Get the name of the block style.
- * @return {?string} Name of the block style.
+ * @return {string} Name of the block style.
 */
 Blockly.Block.prototype.getStyleName = function() {
  return this.styleName_;
@@ -986,7 +987,7 @@ Blockly.Block.prototype.setColour = function(colour) {

 /**
 * Set the style and colour values of a block.
- * @param {string} blockStyleName Name of the block style
+ * @param {string} blockStyleName Name of the block style.
 */
 Blockly.Block.prototype.setStyle = function(blockStyleName) {
  this.styleName_ = blockStyleName;
@@ -1018,7 +1019,7 @@ Blockly.Block.prototype.setOnChange = function(onchangeFn) {
 /**
 * Returns the named field from a block.
 * @param {string} name The name of the field.
- * @return {Blockly.Field} Named field, or null if field does not exist.
+ * @return {?Blockly.Field} Named field, or null if field does not exist.
 */
 Blockly.Block.prototype.getField = function(name) {
  for (var i = 0, input; (input = this.inputList[i]); i++) {
@@ -1957,7 +1958,7 @@ Blockly.Block.prototype.removeInput = function(name, opt_quiet) {
 /**
 * Fetches the named input object.
 * @param {string} name The name of the input.
- * @return {Blockly.Input} The input object, or null if input does not exist.
+ * @return {?Blockly.Input} The input object, or null if input does not exist.
 */
 Blockly.Block.prototype.getInput = function(name) {
  for (var i = 0, input; (input = this.inputList[i]); i++) {
@@ -1972,7 +1973,7 @@ Blockly.Block.prototype.getInput = function(name) {
 /**
 * Fetches the block attached to the named input.
 * @param {string} name The name of the input.
- * @return {Blockly.Block} The attached value block, or null if the input is
+ * @return {?Blockly.Block} The attached value block, or null if the input is
 *     either disconnected or if the input does not exist.
 */
 Blockly.Block.prototype.getInputTargetBlock = function(name) {
--- a/core/block_drag_surface.js
+++ b/core/block_drag_surface.js
@@ -39,7 +39,7 @@ Blockly.BlockDragSurfaceSvg = function(container) {

 /**
 * The SVG drag surface. Set once by Blockly.BlockDragSurfaceSvg.createDom.
- * @type {SVGElement}
+ * @type {?SVGElement}
 * @private
 */
 Blockly.BlockDragSurfaceSvg.prototype.SVG_ = null;
@@ -47,14 +47,14 @@ Blockly.BlockDragSurfaceSvg.prototype.SVG_ = null;
 /**
 * This is where blocks live while they are being dragged if the drag surface
 * is enabled.
- * @type {SVGElement}
+ * @type {?SVGElement}
 * @private
 */
 Blockly.BlockDragSurfaceSvg.prototype.dragGroup_ = null;

 /**
 * Containing HTML element; parent of the workspace and the drag surface.
- * @type {Element}
+ * @type {?Element}
 * @private
 */
 Blockly.BlockDragSurfaceSvg.prototype.container_ = null;
@@ -71,7 +71,7 @@ Blockly.BlockDragSurfaceSvg.prototype.scale_ = 1;
 * Cached value for the translation of the drag surface.
 * This translation is in pixel units, because the scale is applied to the
 * drag group rather than the top-level SVG.
- * @type {Blockly.utils.Coordinate}
+ * @type {?Blockly.utils.Coordinate}
 * @private
 */
 Blockly.BlockDragSurfaceSvg.prototype.surfaceXY_ = null;
@@ -172,7 +172,7 @@ Blockly.BlockDragSurfaceSvg.prototype.getSurfaceTranslation = function() {
 /**
 * Provide a reference to the drag group (primarily for
 * BlockSvg.getRelativeToSurfaceXY).
- * @return {SVGElement} Drag surface group element.
+ * @return {?SVGElement} Drag surface group element.
 */
 Blockly.BlockDragSurfaceSvg.prototype.getGroup = function() {
  return this.dragGroup_;
@@ -181,8 +181,7 @@ Blockly.BlockDragSurfaceSvg.prototype.getGroup = function() {
 /**
 * Get the current blocks on the drag surface, if any (primarily
 * for BlockSvg.getRelativeToSurfaceXY).
- * @return {Element} Drag surface block DOM element, or undefined if no blocks
- * exist.
+ * @return {?Element} Drag surface block DOM element, or null if no blocks exist.
 */
 Blockly.BlockDragSurfaceSvg.prototype.getCurrentBlock = function() {
  return /** @type {Element} */ (this.dragGroup_.firstChild);
--- a/core/block_svg.js
+++ b/core/block_svg.js
@@ -748,7 +748,7 @@ Blockly.BlockSvg.prototype.showHelp = function() {
 /**
 * Generate the context menu for this block.
 * @protected
- * @return {Array<!Object>} Context menu options
+ * @return {?Array<!Object>} Context menu options or null if no menu.
 */
 Blockly.BlockSvg.prototype.generateContextMenu = function() {
  if (this.workspace.options.readOnly || !this.contextMenu) {
@@ -1009,7 +1009,7 @@ Blockly.BlockSvg.prototype.updateDisabled = function() {
 /**
 * Get the comment icon attached to this block, or null if the block has no
 * comment.
- * @return {Blockly.Comment} The comment icon attached to this block, or null.
+ * @return {?Blockly.Comment} The comment icon attached to this block, or null.
 */
 Blockly.BlockSvg.prototype.getCommentIcon = function() {
  return this.commentIcon_;
@@ -1138,7 +1138,7 @@ Blockly.BlockSvg.prototype.setWarningText = function(text, opt_id) {

 /**
 * Give this block a mutator dialog.
- * @param {Blockly.Mutator} mutator A mutator dialog instance or null to remove.
+ * @param {?Blockly.Mutator} mutator A mutator dialog instance or null to remove.
 */
 Blockly.BlockSvg.prototype.setMutator = function(mutator) {
  if (this.mutator && this.mutator !== mutator) {
@@ -1234,7 +1234,7 @@ Blockly.BlockSvg.prototype.setColour = function(colour) {

 /**
 * Set the style and colour values of a block.
- * @param {string} blockStyleName Name of the block style
+ * @param {string} blockStyleName Name of the block style.
 * @throws {Error} if the block style does not exist.
 */
 Blockly.BlockSvg.prototype.setStyle = function(blockStyleName) {
@@ -1473,7 +1473,7 @@ Blockly.BlockSvg.prototype.getConnections_ = function(all) {

 /**
 * Walks down a stack of blocks and finds the last next connection on the stack.
- * @return {Blockly.RenderedConnection} The last next connection on the stack,
+ * @return {?Blockly.RenderedConnection} The last next connection on the stack,
 *     or null.
 * @package
 * @override
@@ -1489,7 +1489,7 @@ Blockly.BlockSvg.prototype.lastConnectionInStack = function() {
 * Used to match connections between a block and its insertion marker.
 * @param {!Blockly.Block} otherBlock The other block to match against.
 * @param {!Blockly.Connection} conn The other connection to match.
- * @return {Blockly.RenderedConnection} The matching connection on this block,
+ * @return {?Blockly.RenderedConnection} The matching connection on this block,
 *     or null.
 * @package
 * @override
@@ -1603,7 +1603,7 @@ Blockly.BlockSvg.prototype.positionNearConnection = function(sourceConnection,

 /**
 * Return the parent block or null if this block is at the top level.
- * @return {Blockly.BlockSvg} The block that holds the current block.
+ * @return {?Blockly.BlockSvg} The block (if any) that holds the current block.
 * @override
 */
 Blockly.BlockSvg.prototype.getParent = function() {
--- a/core/blockly.js
+++ b/core/blockly.js
@@ -468,7 +468,7 @@ Blockly.checkBlockColourConstants = function() {
 * Checks for a constant in the Blockly namespace, verifying it is undefined or
 * has the old/original value. Prints a warning if this is not true.
 * @param {string} msgName The Msg constant identifier.
- * @param {Array<string>} blocklyNamePath The name parts of the tested
+ * @param {!Array<string>} blocklyNamePath The name parts of the tested
 *     constant.
 * @param {number|undefined} expectedValue The expected value of the constant.
 * @private
--- a/core/bubble.js
+++ b/core/bubble.js
@@ -37,7 +37,7 @@ goog.requireType('Blockly.WorkspaceSvg');
 * @param {!Blockly.WorkspaceSvg} workspace The workspace on which to draw the
 *     bubble.
 * @param {!Element} content SVG content for the bubble.
- * @param {Element} shape SVG element to avoid eclipsing.
+ * @param {!Element} shape SVG element to avoid eclipsing.
 * @param {!Blockly.utils.Coordinate} anchorXY Absolute position of bubble's
 *     anchor point.
 * @param {?number} bubbleWidth Width of bubble, or null if not resizable.
--- a/core/connection.js
+++ b/core/connection.js
@@ -378,7 +378,7 @@ Blockly.Connection.connectReciprocally_ = function(first, second) {
 * connections, this returns null.
 * @param {!Blockly.Block} block The superior block.
 * @param {!Blockly.Block} orphanBlock The inferior block.
- * @return {Blockly.Connection} The suitable connection point on 'block',
+ * @return {?Blockly.Connection} The suitable connection point on 'block',
 *     or null.
 * @private
 */
@@ -407,7 +407,7 @@ Blockly.Connection.getSingleConnection_ = function(block, orphanBlock) {
 * Terminates early for shadow blocks.
 * @param {!Blockly.Block} startBlock The block on which to start the search.
 * @param {!Blockly.Block} orphanBlock The block that is looking for a home.
- * @return {Blockly.Connection} The suitable connection point on the chain
+ * @return {?Blockly.Connection} The suitable connection point on the chain
 *     of blocks, or null.
 * @package
 */
@@ -507,7 +507,7 @@ Blockly.Connection.prototype.respawnShadow_ = function() {

 /**
 * Returns the block that this connection connects to.
- * @return {Blockly.Block} The connected block or null if none is connected.
+ * @return {?Blockly.Block} The connected block or null if none is connected.
 */
 Blockly.Connection.prototype.targetBlock = function() {
  if (this.isConnected()) {
@@ -590,7 +590,7 @@ Blockly.Connection.prototype.setCheck = function(check) {

 /**
 * Get a connection's compatibility.
- * @return {Array} List of compatible value types.
+ * @return {?Array} List of compatible value types.
 *     Null if all types are compatible.
 * @public
 */
@@ -600,7 +600,7 @@ Blockly.Connection.prototype.getCheck = function() {

 /**
 * Changes the connection's shadow block.
- * @param {Element} shadow DOM representation of a block or null.
+ * @param {?Element} shadow DOM representation of a block or null.
 */
 Blockly.Connection.prototype.setShadowDom = function(shadow) {
  this.shadowDom_ = shadow;
@@ -615,8 +615,8 @@ Blockly.Connection.prototype.setShadowDom = function(shadow) {
 };

 /**
- * Returns the xml representation of the connection's shadow block.
- * @return {Element} Shadow DOM representation of a block or null.
+ * Returns the XML representation of the connection's shadow block.
+ * @return {?Element} Shadow DOM representation of a block or null.
 */
 Blockly.Connection.prototype.getShadowDom = function() {
  return this.shadowDom_;
@@ -640,7 +640,7 @@ Blockly.Connection.prototype.neighbours = function(_maxLimit) {

 /**
 * Get the parent input of a connection.
- * @return {Blockly.Input} The input that the connection belongs to or null if
+ * @return {?Blockly.Input} The input that the connection belongs to or null if
 *     no parent exists.
 * @package
 */
--- a/core/events/block_events.js
+++ b/core/events/block_events.js
@@ -44,7 +44,7 @@ Blockly.Events.BlockBase = function(opt_block) {
  this.isBlank = typeof opt_block == 'undefined';

  /**
-   * The block id for the block this event pertains to
+   * The block ID for the block this event pertains to
   * @type {string}
   */
  this.blockId = this.isBlank ? '' : opt_block.id;
@@ -332,7 +332,7 @@ Blockly.utils.object.inherits(Blockly.Events.Delete, Blockly.Events.BlockBase);

 /**
 * Class for a block deletion event.
- * @param {Blockly.Block} block The deleted block.  Null for a blank event.
+ * @param {?Blockly.Block} block The deleted block.  Null for a blank event.
 * @extends {Blockly.Events.BlockBase}
 * @constructor
 */
@@ -420,7 +420,7 @@ Blockly.utils.object.inherits(Blockly.Events.Move, Blockly.Events.BlockBase);

 /**
 * Class for a block move event.  Created before the move.
- * @param {Blockly.Block} block The moved block.  Null for a blank event.
+ * @param {?Blockly.Block} block The moved block.  Null for a blank event.
 * @extends {Blockly.Events.BlockBase}
 * @constructor
 */
--- a/core/field.js
+++ b/core/field.js
@@ -536,7 +536,7 @@ Blockly.Field.prototype.setValidator = function(handler) {

 /**
 * Gets the validation function for editable fields, or null if not set.
- * @return {Function} Validation function, or null.
+ * @return {?Function} Validation function, or null.
 */
 Blockly.Field.prototype.getValidator = function() {
  return this.validator_;
--- a/core/field_colour.js
+++ b/core/field_colour.js
@@ -473,7 +473,7 @@ Blockly.FieldColour.prototype.onMouseLeave_ = function() {

 /**
 * Returns the currently highlighted item (if any).
- * @return {HTMLElement} Highlighted item (null if none).
+ * @return {?HTMLElement} Highlighted item (null if none).
 * @private
 */
 Blockly.FieldColour.prototype.getHighlighted_ = function() {
--- a/core/field_registry.js
+++ b/core/field_registry.js
@@ -49,7 +49,7 @@ Blockly.fieldRegistry.unregister = function(type) {
 * Blockly.fieldRegistry.register.
 * @param {!Object} options A JSON object with a type and options specific
 *     to the field type.
- * @return {Blockly.Field} The new field instance or null if a field wasn't
+ * @return {?Blockly.Field} The new field instance or null if a field wasn't
 *     found with the given type name
 * @package
 */
--- a/core/field_variable.js
+++ b/core/field_variable.js
@@ -225,7 +225,7 @@ Blockly.FieldVariable.prototype.getText = function() {
 * Get the variable model for the selected variable.
 * Not guaranteed to be in the variable map on the workspace (e.g. if accessed
 * after the variable has been deleted).
- * @return {Blockly.VariableModel} The selected variable, or null if none was
+ * @return {?Blockly.VariableModel} The selected variable, or null if none was
 *     selected.
 * @package
 */
@@ -238,7 +238,7 @@ Blockly.FieldVariable.prototype.getVariable = function() {
 * Returns null if the variable is not set, because validators should not
 * run on the initial setValue call, because the field won't be attached to
 * a block and workspace at that point.
- * @return {Function} Validation function, or null.
+ * @return {?Function} Validation function, or null.
 */
 Blockly.FieldVariable.prototype.getValidator = function() {
  // Validators shouldn't operate on the initial setValue call.
--- a/core/flyout_base.js
+++ b/core/flyout_base.js
@@ -1019,7 +1019,7 @@ Blockly.Flyout.prototype.placeNewBlock_ = function(oldBlock) {

 /**
 * Return the deletion rectangle for this flyout in viewport coordinates.
- * @return {Blockly.utils.Rect} Rectangle in which to delete.
+ * @return {?Blockly.utils.Rect} Rectangle in which to delete.
 */
 Blockly.Flyout.prototype.getClientRect;

--- a/core/flyout_horizontal.js
+++ b/core/flyout_horizontal.js
@@ -305,7 +305,7 @@ Blockly.HorizontalFlyout.prototype.isDragTowardWorkspace = function(

 /**
 * Return the deletion rectangle for this flyout in viewport coordinates.
- * @return {Blockly.utils.Rect} Rectangle in which to delete.
+ * @return {?Blockly.utils.Rect} Rectangle in which to delete.
 */
 Blockly.HorizontalFlyout.prototype.getClientRect = function() {
  if (!this.svgGroup_) {
--- a/core/flyout_vertical.js
+++ b/core/flyout_vertical.js
@@ -288,7 +288,7 @@ Blockly.VerticalFlyout.prototype.isDragTowardWorkspace = function(

 /**
 * Return the deletion rectangle for this flyout in viewport coordinates.
- * @return {Blockly.utils.Rect} Rectangle in which to delete.
+ * @return {?Blockly.utils.Rect} Rectangle in which to delete.
 */
 Blockly.VerticalFlyout.prototype.getClientRect = function() {
  if (!this.svgGroup_) {
--- a/core/generator.js
+++ b/core/generator.js
@@ -88,7 +88,7 @@ Blockly.Generator.prototype.isInitialized = null;

 /**
 * Generate code for all blocks in the workspace to the specified language.
- * @param {Blockly.Workspace} workspace Workspace to generate code from.
+ * @param {!Blockly.Workspace=} workspace Workspace to generate code from.
 * @return {string} Generated code.
 */
 Blockly.Generator.prototype.workspaceToCode = function(workspace) {
@@ -384,7 +384,7 @@ Blockly.Generator.prototype.FUNCTION_NAME_PLACEHOLDER_ = '{leCUI8hutHZI4480Dc}';

 /**
 * A dictionary of definitions to be printed before the code.
- * @type {Object}
+ * @type {!Object|undefined}
 * @protected
 */
 Blockly.Generator.prototype.definitions_;
@@ -392,14 +392,14 @@ Blockly.Generator.prototype.definitions_;
 /**
 * A dictionary mapping desired function names in definitions_ to actual
 * function names (to avoid collisions with user functions).
- * @type {Object}
+ * @type {!Object|undefined}
 * @protected
 */
 Blockly.Generator.prototype.functionNames_;

 /**
 * A database of variable and procedure names.
- * @type {Blockly.Names}
+ * @type {!Blockly.Names|undefined}
 * @protected
 */
 Blockly.Generator.prototype.nameDB_;
--- a/core/icon.js
+++ b/core/icon.js
@@ -56,14 +56,14 @@ Blockly.Icon.prototype.SIZE = 17;

 /**
 * Bubble UI (if visible).
- * @type {Blockly.Bubble}
+ * @type {?Blockly.Bubble}
 * @protected
 */
 Blockly.Icon.prototype.bubble_ = null;

 /**
 * Absolute coordinate of icon's center.
- * @type {Blockly.utils.Coordinate}
+ * @type {?Blockly.utils.Coordinate}
 * @protected
 */
 Blockly.Icon.prototype.iconXY_ = null;
@@ -177,7 +177,7 @@ Blockly.Icon.prototype.computeIconLocation = function() {

 /**
 * Returns the center of the block's icon relative to the surface.
- * @return {Blockly.utils.Coordinate} Object with x and y properties in
+ * @return {?Blockly.utils.Coordinate} Object with x and y properties in
 *     workspace coordinates.
 */
 Blockly.Icon.prototype.getIconLocation = function() {
--- a/core/input.js
+++ b/core/input.js
@@ -69,7 +69,7 @@ Blockly.Input.prototype.visible_ = true;

 /**
 * Get the source block for this input.
- * @return {Blockly.Block} The source block, or null if there is none.
+ * @return {?Blockly.Block} The source block, or null if there is none.
 */
 Blockly.Input.prototype.getSourceBlock = function() {
  return this.sourceBlock_;
@@ -259,8 +259,8 @@ Blockly.Input.prototype.setAlign = function(align) {

 /**
 * Changes the connection's shadow block.
- * @param {Element} shadow DOM representation of a block or null.
- * @return {Blockly.Input} The input being modified (to allow chaining).
+ * @param {?Element} shadow DOM representation of a block or null.
+ * @return {!Blockly.Input} The input being modified (to allow chaining).
 */
 Blockly.Input.prototype.setShadowDom = function(shadow) {
  if (!this.connection) {
@@ -271,8 +271,8 @@ Blockly.Input.prototype.setShadowDom = function(shadow) {
 };

 /**
- * Returns the xml representation of the connection's shadow block.
- * @return {Element} Shadow DOM representation of a block or null.
+ * Returns the XML representation of the connection's shadow block.
+ * @return {?Element} Shadow DOM representation of a block or null.
 */
 Blockly.Input.prototype.getShadowDom = function() {
  if (!this.connection) {
--- a/core/marker_manager.js
+++ b/core/marker_manager.js
@@ -27,14 +27,14 @@ goog.requireType('Blockly.WorkspaceSvg');
 Blockly.MarkerManager = function(workspace){
  /**
   * The cursor.
-   * @type {Blockly.Cursor}
+   * @type {?Blockly.Cursor}
   * @private
   */
  this.cursor_ = null;

  /**
-   * The cursor's svg element.
-   * @type {SVGElement}
+   * The cursor's SVG element.
+   * @type {?SVGElement}
   * @private
   */
  this.cursorSvg_ = null;
@@ -44,7 +44,7 @@ Blockly.MarkerManager = function(workspace){
   * @type {!Object<string, !Blockly.Marker>}
   * @private
   */
-  this.markers_ = {};
+  this.markers_ = Object.create(null);

  /**
   * The workspace this marker manager is associated with.
@@ -86,14 +86,14 @@ Blockly.MarkerManager.prototype.unregisterMarker = function(id) {
    marker.dispose();
    delete this.markers_[id];
  } else {
-    throw Error('Marker with id ' + id + ' does not exist. Can only unregister' +
-        'markers that exist.');
+    throw Error('Marker with ID ' + id + ' does not exist. ' +
+        'Can only unregister markers that exist.');
  }
 };

 /**
 * Get the cursor for the workspace.
- * @return {Blockly.Cursor} The cursor for this workspace.
+ * @return {?Blockly.Cursor} The cursor for this workspace.
 */
 Blockly.MarkerManager.prototype.getCursor = function() {
  return this.cursor_;
@@ -102,11 +102,11 @@ Blockly.MarkerManager.prototype.getCursor = function() {
 /**
 * Get a single marker that corresponds to the given ID.
 * @param {string} id A unique identifier for the marker.
- * @return {Blockly.Marker} The marker that corresponds to the given ID, or null
- *     if none exists.
+ * @return {?Blockly.Marker} The marker that corresponds to the given ID,
+ *     or null if none exists.
 */
 Blockly.MarkerManager.prototype.getMarker = function(id) {
-  return this.markers_[id];
+  return this.markers_[id] || null;
 };

 /**
@@ -128,7 +128,7 @@ Blockly.MarkerManager.prototype.setCursor = function(cursor) {

 /**
 * Add the cursor SVG to this workspace SVG group.
- * @param {SVGElement} cursorSvg The SVG root of the cursor to be added to the
+ * @param {?SVGElement} cursorSvg The SVG root of the cursor to be added to the
 *     workspace SVG group.
 * @package
 */
@@ -144,7 +144,7 @@ Blockly.MarkerManager.prototype.setCursorSvg = function(cursorSvg) {

 /**
 * Add the marker SVG to this workspaces SVG group.
- * @param {SVGElement} markerSvg The SVG root of the marker to be added to the
+ * @param {?SVGElement} markerSvg The SVG root of the marker to be added to the
 *     workspace SVG group.
 * @package
 */
--- a/core/menu.js
+++ b/core/menu.js
@@ -49,7 +49,7 @@ Blockly.Menu = function() {
  /**
   * This is the element that we will listen to the real focus events on.
   * A value of null means no menu item is highlighted.
-   * @type {Blockly.MenuItem}
+   * @type {?Blockly.MenuItem}
   * @private
   */
  this.highlightedItem_ = null;
@@ -91,7 +91,7 @@ Blockly.Menu = function() {

  /**
   * The menu's root DOM element.
-   * @type {Element}
+   * @type {?Element}
   * @private
   */
  this.element_ = null;
@@ -149,7 +149,7 @@ Blockly.Menu.prototype.render = function(container) {

 /**
 * Gets the menu's element.
- * @return {Element} The DOM element.
+ * @return {?Element} The DOM element.
 * @package
 */
 Blockly.Menu.prototype.getElement = function() {
@@ -255,7 +255,7 @@ Blockly.Menu.prototype.getMenuItem_ = function(elem) {

 /**
 * Highlights the given menu item, or clears highlighting if null.
- * @param {Blockly.MenuItem} item Item to highlight, or null.
+ * @param {?Blockly.MenuItem} item Item to highlight, or null.
 * @package
 */
 Blockly.Menu.prototype.setHighlighted = function(item) {
@@ -382,7 +382,7 @@ Blockly.Menu.prototype.handleClick_ = function(e) {

 /**
 * Handles mouse enter events. Focus the element.
- * @param {Event} _e Mouse event to handle.
+ * @param {!Event} _e Mouse event to handle.
 * @private
 */
 Blockly.Menu.prototype.handleMouseEnter_ = function(_e) {
@@ -391,7 +391,7 @@ Blockly.Menu.prototype.handleMouseEnter_ = function(_e) {

 /**
 * Handles mouse leave events. Blur and clear highlight.
- * @param {Event} _e Mouse event to handle.
+ * @param {!Event} _e Mouse event to handle.
 * @private
 */
 Blockly.Menu.prototype.handleMouseLeave_ = function(_e) {
--- a/core/menuitem.js
+++ b/core/menuitem.js
@@ -91,7 +91,7 @@ Blockly.MenuItem = function(content, opt_value) {

  /**
   * Bound function to call when this menu item is clicked.
-   * @type {Function}
+   * @type {?Function}
   * @private
   */
  this.actionHandler_ = null;
@@ -153,7 +153,7 @@ Blockly.MenuItem.prototype.dispose = function() {

 /**
 * Gets the menu item's element.
- * @return {Element} The DOM element.
+ * @return {?Element} The DOM element.
 * @package
 */
 Blockly.MenuItem.prototype.getElement = function() {
--- a/core/mutator.js
+++ b/core/mutator.js
@@ -50,6 +50,13 @@ Blockly.Mutator = function(quarkNames) {
 };
 Blockly.utils.object.inherits(Blockly.Mutator, Blockly.Icon);

+/**
+ * Workspace in the mutator's bubble.
+ * @type {?Blockly.WorkspaceSvg}
+ * @private
+ */
+Blockly.Mutator.prototype.workspace_ = null;
+
 /**
 * Width of workspace.
 * @private
@@ -64,7 +71,7 @@ Blockly.Mutator.prototype.workspaceHeight_ = 0;

 /**
 * Set the block this mutator is associated with.
- * @param {Blockly.BlockSvg} block The block associated with this mutator.
+ * @param {!Blockly.BlockSvg} block The block associated with this mutator.
 * @package
 */
 Blockly.Mutator.prototype.setBlock = function(block) {
@@ -73,8 +80,8 @@ Blockly.Mutator.prototype.setBlock = function(block) {

 /**
 * Returns the workspace inside this mutator icon's bubble.
- * @return {Blockly.WorkspaceSvg} The workspace inside this mutator icon's
- *     bubble.
+ * @return {?Blockly.WorkspaceSvg} The workspace inside this mutator icon's
+ *     bubble or null if the mutator isn't open.
 * @package
 */
 Blockly.Mutator.prototype.getWorkspace = function() {
@@ -466,16 +473,14 @@ Blockly.Mutator.prototype.updateBlockStyle = function() {

  if (ws && ws.getAllBlocks(false)) {
    var workspaceBlocks = ws.getAllBlocks(false);
-    for (var i = 0; i < workspaceBlocks.length; i++) {
-      var block = workspaceBlocks[i];
+    for (var i = 0, block; (block = workspaceBlocks[i]); i++) {
      block.setStyle(block.getStyleName());
    }

    var flyout = ws.getFlyout();
    if (flyout) {
      var flyoutBlocks = flyout.workspace_.getAllBlocks(false);
-      for (var i = 0; i < flyoutBlocks.length; i++) {
-        var block = flyoutBlocks[i];
+      for (var i = 0, block; (block = flyoutBlocks[i]); i++) {
        block.setStyle(block.getStyleName());
      }
    }
@@ -511,7 +516,7 @@ Blockly.Mutator.reconnect = function(connectionChild, block, inputName) {
 * Get the parent workspace of a workspace that is inside a mutator, taking into
 * account whether it is a flyout.
 * @param {Blockly.Workspace} workspace The workspace that is inside a mutator.
- * @return {Blockly.Workspace} The mutator's parent workspace or null.
+ * @return {?Blockly.Workspace} The mutator's parent workspace or null.
 * @public
 */
 Blockly.Mutator.findParentWs = function(workspace) {
--- a/core/procedures.js
+++ b/core/procedures.js
@@ -391,7 +391,7 @@ Blockly.Procedures.mutateCallers = function(defBlock) {
 * Find the definition block for the named procedure.
 * @param {string} name Name of procedure.
 * @param {!Blockly.Workspace} workspace The workspace to search.
- * @return {Blockly.Block} The procedure definition block, or null not found.
+ * @return {?Blockly.Block} The procedure definition block, or null not found.
 */
 Blockly.Procedures.getDefinition = function(name, workspace) {
  // Do not assume procedure is a top block. Some languages allow nested
--- a/core/registry.js
+++ b/core/registry.js
@@ -260,7 +260,7 @@ Blockly.registry.getClass = function(type, name, opt_throwIfMissing) {
 * @param {string} name The plugin's name. (Ex. logic_category)
 * @param {boolean=} opt_throwIfMissing Whether or not to throw an error if we
 *     are unable to find the object.
- * @return {T} The object with the given name and type or null if none exists.
+ * @return {?T} The object with the given name and type or null if none exists.
 * @template T
 */
 Blockly.registry.getObject = function(type, name, opt_throwIfMissing) {
--- a/core/rendered_connection.js
+++ b/core/rendered_connection.js
@@ -119,7 +119,7 @@ Blockly.RenderedConnection.prototype.getSourceBlock = function() {

 /**
 * Returns the block that this connection connects to.
- * @return {Blockly.BlockSvg} The connected block or null if none is connected.
+ * @return {?Blockly.BlockSvg} The connected block or null if none is connected.
 * @override
 */
 Blockly.RenderedConnection.prototype.targetBlock = function() {
--- a/core/scrollbar.js
+++ b/core/scrollbar.js
@@ -496,32 +496,24 @@ Blockly.Scrollbar.DEFAULT_SCROLLBAR_MARGIN = 0.5;


 /**
- * @param {Blockly.utils.Metrics} first An object containing computed
+ * @param {!Blockly.utils.Metrics} first An object containing computed
 *     measurements of a workspace.
- * @param {?Blockly.utils.Metrics} second Another object containing computed
+ * @param {!Blockly.utils.Metrics} second Another object containing computed
 *     measurements of a workspace.
 * @return {boolean} Whether the two sets of metrics are equivalent.
 * @private
 */
 Blockly.Scrollbar.metricsAreEquivalent_ = function(first, second) {
-  if (!(first && second)) {
-    return false;
-  }
-
-  if (first.viewWidth != second.viewWidth ||
-      first.viewHeight != second.viewHeight ||
-      first.viewLeft != second.viewLeft ||
-      first.viewTop != second.viewTop ||
-      first.absoluteTop != second.absoluteTop ||
-      first.absoluteLeft != second.absoluteLeft ||
-      first.scrollWidth != second.scrollWidth ||
-      first.scrollHeight != second.scrollHeight ||
-      first.scrollLeft != second.scrollLeft ||
-      first.scrollTop != second.scrollTop) {
-    return false;
-  }
-
-  return true;
+  return (first.viewWidth == second.viewWidth &&
+      first.viewHeight == second.viewHeight &&
+      first.viewLeft == second.viewLeft &&
+      first.viewTop == second.viewTop &&
+      first.absoluteTop == second.absoluteTop &&
+      first.absoluteLeft == second.absoluteLeft &&
+      first.scrollWidth == second.scrollWidth &&
+      first.scrollHeight == second.scrollHeight &&
+      first.scrollLeft == second.scrollLeft &&
+      first.scrollTop == second.scrollTop);
 };

 /**
@@ -649,8 +641,8 @@ Blockly.Scrollbar.prototype.resize = function(opt_metrics) {
    }
  }

-  if (Blockly.Scrollbar.metricsAreEquivalent_(hostMetrics,
-      this.oldHostMetrics_)) {
+  if (this.oldHostMetrics_ && Blockly.Scrollbar.metricsAreEquivalent_(
+      hostMetrics, this.oldHostMetrics_)) {
    return;
  }

@@ -671,7 +663,7 @@ Blockly.Scrollbar.prototype.resize = function(opt_metrics) {
 * hostMetrics with cached old host metrics.
 * @param {!Blockly.utils.Metrics} hostMetrics A data structure describing all
 *     the required dimensions, possibly fetched from the host object.
- * @return {boolean} Whether a resizeView is necesssary.
+ * @return {boolean} Whether a resizeView is necessary.
 * @private
 */
 Blockly.Scrollbar.prototype.requiresViewResize_ = function(hostMetrics) {
@@ -723,8 +715,8 @@ Blockly.Scrollbar.prototype.resizeViewHorizontal = function(hostMetrics) {
      Blockly.Scrollbar.scrollbarThickness - this.margin_;
  this.setPosition(xCoordinate, yCoordinate);

-  // If the view has been resized, a content resize will also be necessary.  The
-  // reverse is not true.
+  // If the view has been resized, a content resize will also be necessary.
+  // The reverse is not true.
  this.resizeContentHorizontal(hostMetrics);
 };

--- a/core/touch_gesture.js
+++ b/core/touch_gesture.js
@@ -314,7 +314,7 @@ Blockly.TouchGesture.prototype.handleTouchEnd = function(e) {
 /**
 * Helper function returning the current touch point coordinate.
 * @param {!Event} e A touch or pointer event.
- * @return {Blockly.utils.Coordinate} The current touch point coordinate
+ * @return {?Blockly.utils.Coordinate} The current touch point coordinate
 * @package
 */
 Blockly.TouchGesture.prototype.getTouchPoint = function(e) {
--- a/core/trashcan.js
+++ b/core/trashcan.js
@@ -507,7 +507,7 @@ Blockly.Trashcan.prototype.getBoundingRectangle = function() {

 /**
 * Return the deletion rectangle for this trash can.
- * @return {Blockly.utils.Rect} Rectangle in which to delete.
+ * @return {?Blockly.utils.Rect} Rectangle in which to delete.
 */
 Blockly.Trashcan.prototype.getClientRect = function() {
  if (!this.svgGroup_) {
--- a/core/variable_map.js
+++ b/core/variable_map.js
@@ -293,7 +293,7 @@ Blockly.VariableMap.prototype.deleteVariableInternal = function(variable,
 * @param {string} name The name to check for.
 * @param {?string=} opt_type The type of the variable.  If not provided it
 *     defaults to the empty string, which is a specific type.
- * @return {Blockly.VariableModel} The variable with the given name, or null if
+ * @return {?Blockly.VariableModel} The variable with the given name, or null if
 *     it was not found.
 */
 Blockly.VariableMap.prototype.getVariable = function(name, opt_type) {
@@ -310,10 +310,9 @@ Blockly.VariableMap.prototype.getVariable = function(name, opt_type) {
 };

 /**
- * Find the variable by the given ID and return it. Return null if it is not
- *     found.
+ * Find the variable by the given ID and return it.  Return null if not found.
 * @param {string} id The ID to check for.
- * @return {Blockly.VariableModel} The variable with the given ID.
+ * @return {?Blockly.VariableModel} The variable with the given ID.
 */
 Blockly.VariableMap.prototype.getVariableById = function(id) {
  var keys = Object.keys(this.variableMap_);
--- a/core/variables.js
+++ b/core/variables.js
@@ -392,7 +392,7 @@ Blockly.Variables.promptName = function(promptText, defaultText, callback) {
 * @param {string} type The type to exclude from the search.
 * @param {!Blockly.Workspace} workspace The workspace to search for the
 *     variable.
- * @return {Blockly.VariableModel} The variable with the given name and a
+ * @return {?Blockly.VariableModel} The variable with the given name and a
 *     different type, or null if none was found.
 * @private
 */
@@ -413,7 +413,7 @@ Blockly.Variables.nameUsedWithOtherType_ = function(name, type, workspace) {
 * @param {string} name The name to search for.
 * @param {!Blockly.Workspace} workspace The workspace to search for the
 *     variable.
- * @return {Blockly.VariableModel} The variable with the given name,
+ * @return {?Blockly.VariableModel} The variable with the given name,
 *     or null if none was found.
 */
 Blockly.Variables.nameUsedWithAnyType = function(name, workspace) {
@@ -432,7 +432,7 @@ Blockly.Variables.nameUsedWithAnyType = function(name, workspace) {
 * Generate DOM objects representing a variable field.
 * @param {!Blockly.VariableModel} variableModel The variable model to
 *     represent.
- * @return {Element} The generated DOM.
+ * @return {?Element} The generated DOM.
 * @public
 */
 Blockly.Variables.generateVariableFieldDom = function(variableModel) {
@@ -482,7 +482,7 @@ Blockly.Variables.getOrCreateVariablePackage = function(workspace, id, opt_name,
 *     Only used if lookup by ID fails.
 * @param {string=} opt_type The type to use to look up the variable.
 *     Only used if lookup by ID fails.
- * @return {Blockly.VariableModel} The variable corresponding to the given ID
+ * @return {?Blockly.VariableModel} The variable corresponding to the given ID
 *     or name + type combination, or null if not found.
 * @public
 */
--- a/core/workspace.js
+++ b/core/workspace.js
@@ -116,7 +116,7 @@ Blockly.Workspace = function(opt_options) {
   * A FieldVariable must always refer to a Blockly.VariableModel.  We reconcile
   * these by tracking "potential" variables in the flyout.  These variables
   * become real when references to them are dragged into the main workspace.
-   * @type {Blockly.VariableMap}
+   * @type {?Blockly.VariableMap}
   * @private
   */
  this.potentialVariableMap_ = null;
@@ -427,12 +427,11 @@ Blockly.Workspace.prototype.deleteVariableById = function(id) {
 };

 /**
- * Find the variable by the given name and return it. Return null if it is not
- *     found.
+ * Find the variable by the given name and return it. Return null if not found.
 * @param {string} name The name to check for.
 * @param {string=} opt_type The type of the variable.  If not provided it
 *     defaults to the empty string, which is a specific type.
- * @return {Blockly.VariableModel} The variable with the given name.
+ * @return {?Blockly.VariableModel} The variable with the given name.
 */
 // TODO (#1559): Possibly delete this function after resolving #1559.
 Blockly.Workspace.prototype.getVariable = function(name, opt_type) {
@@ -440,10 +439,9 @@ Blockly.Workspace.prototype.getVariable = function(name, opt_type) {
 };

 /**
- * Find the variable by the given ID and return it. Return null if it is not
- *     found.
+ * Find the variable by the given ID and return it. Return null if not found.
 * @param {string} id The ID to check for.
- * @return {Blockly.VariableModel} The variable with the given ID.
+ * @return {?Blockly.VariableModel} The variable with the given ID.
 */
 Blockly.Workspace.prototype.getVariableById = function(id) {
  return this.variableMap_.getVariableById(id);
@@ -650,7 +648,7 @@ Blockly.Workspace.prototype.addChangeListener = function(func) {

 /**
 * Stop listening for this workspace's changes.
- * @param {Function} func Function to stop calling.
+ * @param {!Function} func Function to stop calling.
 */
 Blockly.Workspace.prototype.removeChangeListener = function(func) {
  Blockly.utils.arrayRemove(this.listeners_, func);
@@ -733,7 +731,7 @@ Blockly.Workspace.prototype.allInputsFilled = function(
 /**
 * Return the variable map that contains "potential" variables.
 * These exist in the flyout but not in the workspace.
- * @return {Blockly.VariableMap} The potential variable map.
+ * @return {?Blockly.VariableMap} The potential variable map.
 * @package
 */
 Blockly.Workspace.prototype.getPotentialVariableMap = function() {
@@ -765,6 +763,7 @@ Blockly.Workspace.prototype.setVariableMap = function(variableMap) {
  this.variableMap_ = variableMap;
 };

+
 /**
 * Database of all workspaces.
 * @private
@@ -774,7 +773,7 @@ Blockly.Workspace.WorkspaceDB_ = Object.create(null);
 /**
 * Find the workspace with the specified ID.
 * @param {string} id ID of workspace to find.
- * @return {Blockly.Workspace} The sought after workspace or null if not found.
+ * @return {?Blockly.Workspace} The sought after workspace or null if not found.
 */
 Blockly.Workspace.getById = function(id) {
  return Blockly.Workspace.WorkspaceDB_[id] || null;
--- a/core/workspace_svg.js
+++ b/core/workspace_svg.js
@@ -502,7 +502,7 @@ Blockly.WorkspaceSvg.prototype.targetWorkspace = null;

 /**
 * Inverted screen CTM, for use in mouseToSvg.
- * @type {SVGMatrix}
+ * @type {?SVGMatrix}
 * @private
 */
 Blockly.WorkspaceSvg.prototype.inverseScreenCTM_ = null;
@@ -516,7 +516,7 @@ Blockly.WorkspaceSvg.prototype.inverseScreenCTMDirty_ = true;

 /**
 * Get the marker manager for this workspace.
- * @return {Blockly.MarkerManager} The marker manager.
+ * @return {!Blockly.MarkerManager} The marker manager.
 */
 Blockly.WorkspaceSvg.prototype.getMarkerManager = function() {
  return this.markerManager_;
@@ -573,8 +573,8 @@ Blockly.WorkspaceSvg.prototype.setMarkerSvg = function(markerSvg) {
 /**
 * Get the marker with the given ID.
 * @param {string} id The ID of the marker.
- * @return {Blockly.Marker} The marker with the given ID or null if no marker
- *     with the given id exists.
+ * @return {?Blockly.Marker} The marker with the given ID or null if no marker
+ *     with the given ID exists.
 * @package
 */
 Blockly.WorkspaceSvg.prototype.getMarker = function(id) {
@@ -586,7 +586,7 @@ Blockly.WorkspaceSvg.prototype.getMarker = function(id) {

 /**
 * The cursor for this workspace.
- * @return {Blockly.Cursor} The cursor for the workspace.
+ * @return {?Blockly.Cursor} The cursor for the workspace.
 */
 Blockly.WorkspaceSvg.prototype.getCursor = function() {
  if (this.markerManager_) {
@@ -597,7 +597,8 @@ Blockly.WorkspaceSvg.prototype.getCursor = function() {

 /**
 * Get the block renderer attached to this workspace.
- * @return {!Blockly.blockRendering.Renderer} The renderer attached to this workspace.
+ * @return {!Blockly.blockRendering.Renderer} The renderer attached to this
+ *     workspace.
 */
 Blockly.WorkspaceSvg.prototype.getRenderer = function() {
  return this.renderer_;
@@ -644,7 +645,7 @@ Blockly.WorkspaceSvg.prototype.refreshTheme = function() {
  // Update all blocks in workspace that have a style name.
  this.updateBlockStyles_(this.getAllBlocks(false).filter(
      function(block) {
-        return block.getStyleName() !== undefined;
+        return !!block.getStyleName();
      }
  ));

@@ -684,7 +685,7 @@ Blockly.WorkspaceSvg.prototype.updateBlockStyles_ = function(blocks) {

 /**
 * Getter for the inverted screen CTM.
- * @return {SVGMatrix} The matrix to use in mouseToSvg
+ * @return {?SVGMatrix} The matrix to use in mouseToSvg
 */
 Blockly.WorkspaceSvg.prototype.getInverseScreenCTM = function() {
  // Defer getting the screen CTM until we actually need it, this should
@@ -798,7 +799,7 @@ Blockly.WorkspaceSvg.prototype.getInjectionDiv = function() {

 /**
 * Get the SVG block canvas for the workspace.
- * @return {SVGElement} The SVG group for the workspace.
+ * @return {?SVGElement} The SVG group for the workspace.
 * @package
 */
 Blockly.WorkspaceSvg.prototype.getBlockCanvas = function() {
@@ -1066,7 +1067,7 @@ Blockly.WorkspaceSvg.prototype.addFlyout = function(tagName) {
 * owned by either the toolbox or the workspace, depending on toolbox
 * configuration.  It will be null if there is no flyout.
 * @param {boolean=} opt_own Whether to only return the workspace's own flyout.
- * @return {Blockly.IFlyout} The flyout on this workspace.
+ * @return {?Blockly.IFlyout} The flyout on this workspace.
 * @package
 */
 Blockly.WorkspaceSvg.prototype.getFlyout = function(opt_own) {
@@ -1081,7 +1082,7 @@ Blockly.WorkspaceSvg.prototype.getFlyout = function(opt_own) {

 /**
 * Getter for the toolbox associated with this workspace, if one exists.
- * @return {Blockly.IToolbox} The toolbox on this workspace.
+ * @return {?Blockly.IToolbox} The toolbox on this workspace.
 * @package
 */
 Blockly.WorkspaceSvg.prototype.getToolbox = function() {
@@ -1330,7 +1331,7 @@ Blockly.WorkspaceSvg.prototype.setupDragSurface = function() {
 };

 /**
- * @return {Blockly.BlockDragSurfaceSvg} This workspace's block drag surface,
+ * @return {?Blockly.BlockDragSurfaceSvg} This workspace's block drag surface,
 *     if one is in use.
 * @package
 */
@@ -2314,7 +2315,7 @@ Blockly.WorkspaceSvg.setTopLevelWorkspaceMetrics_ = function(xyRatio) {
 /**
 * Find the block on this workspace with the specified ID.
 * @param {string} id ID of block to find.
- * @return {Blockly.BlockSvg} The sought after block, or null if not found.
+ * @return {?Blockly.BlockSvg} The sought after block, or null if not found.
 * @override
 */
 Blockly.WorkspaceSvg.prototype.getBlockById = function(id) {
@@ -2499,7 +2500,7 @@ Blockly.WorkspaceSvg.prototype.removeToolboxCategoryCallback = function(key) {
 * Look up the gesture that is tracking this touch stream on this workspace.
 * May create a new gesture.
 * @param {!Event} e Mouse event or touch event.
- * @return {Blockly.TouchGesture} The gesture that is tracking this touch
+ * @return {?Blockly.TouchGesture} The gesture that is tracking this touch
 *     stream, or null if no valid gesture exists.
 * @package
 */
@@ -2557,7 +2558,7 @@ Blockly.WorkspaceSvg.prototype.getAudioManager = function() {

 /**
 * Get the grid object for this workspace, or null if there is none.
- * @return {Blockly.Grid} The grid object for this workspace.
+ * @return {?Blockly.Grid} The grid object for this workspace.
 * @package
 */
 Blockly.WorkspaceSvg.prototype.getGrid = function() {
--- a/core/xml.js
+++ b/core/xml.js
@@ -109,7 +109,7 @@ Blockly.Xml.blockToDomWithXY = function(block, opt_noId) {
 /**
 * Encode a field as XML.
 * @param {!Blockly.Field} field The field to encode.
- * @return {Element} XML element, or null if the field did not need to be
+ * @return {?Element} XML element, or null if the field did not need to be
 *     serialized.
 * @private
 */
@@ -375,7 +375,7 @@ Blockly.Xml.textToDom = function(text) {
 * create blocks on the workspace.
 * @param {!Element} xml XML DOM.
 * @param {!Blockly.Workspace} workspace The workspace.
- * @return {Array<string>} An array containing new block ids.
+ * @return {!Array<string>} An array containing new block IDs.
 */
 Blockly.Xml.clearWorkspaceAndLoadFromXml = function(xml, workspace) {
  workspace.setResizesEnabled(false);
@@ -489,7 +489,7 @@ Blockly.Xml.domToWorkspace = function(xml, workspace) {
 * blocks immediately below prior blocks, aligned by their starting edge.
 * @param {!Element} xml The XML DOM.
 * @param {!Blockly.Workspace} workspace The workspace to add to.
- * @return {Array<string>} An array containing new block IDs.
+ * @return {!Array<string>} An array containing new block IDs.
 */
 Blockly.Xml.appendDomToWorkspace = function(xml, workspace) {
  var bbox;  // Bounding box of the current blocks.
@@ -640,7 +640,7 @@ Blockly.Xml.childNodeTagMap;
 * Creates a mapping of childNodes for each supported xml tag for the provided
 * xmlBlock. Logs a warning for any encountered unsupported tags.
 * @param {!Element} xmlBlock XML block element.
- * @return {Blockly.Xml.childNodeTagMap} The childNode map from nodeName to
+ * @return {!Blockly.Xml.childNodeTagMap} The childNode map from nodeName to
 *    node.
 */
 Blockly.Xml.mapSupportedXmlTags_ = function(xmlBlock) {