Corrections to JSDoc comments

core/blockly.js

@@ -114,7 +114,7 @@ Blockly.cache3dSupported_ = null;
 
 /**
  * Holds all Blockly style attributes.
- * @type {?Blockly.Theme}
+ * @type {Blockly.Theme}
  * @private
  */
 Blockly.theme_ = null;
@@ -745,7 +745,7 @@ Blockly.updateBlockStyles_ = function(blocks) {
 
 /**
  * Gets the theme.
- * @return {?Blockly.Theme} Theme for Blockly.
+ * @return {Blockly.Theme} Theme for Blockly.
  */
 Blockly.getTheme = function() {
   return this.theme_;

core/bubble.js

@@ -458,8 +458,8 @@ Blockly.Bubble.prototype.layoutBubble_ = function() {
  * workspace (what percentage of the bubble is visible).
  * @param {!Object} relativeMin The position of the top-left corner of the
  *    bubble relative to the anchor point.
- * @param {!number} relativeMin.x The x-position of the relativeMin.
- * @param {!number} relativeMin.y The y-position of the relativeMin.
+ * @param {number} relativeMin.x The x-position of the relativeMin.
+ * @param {number} relativeMin.y The y-position of the relativeMin.
  * @param {!Object} metrics The metrics of the workspace the bubble will
  *    appear in.
  * @return {number} The percentage of the bubble that is visible.
@@ -772,7 +772,7 @@ Blockly.Bubble.prototype.dispose = function() {
 /**
  * Move this bubble during a drag, taking into account whether or not there is
  * a drag surface.
- * @param {?Blockly.BlockDragSurfaceSvg} dragSurface The surface that carries
+ * @param {Blockly.BlockDragSurfaceSvg} dragSurface The surface that carries
  *     rendered items during a drag, or null if no drag surface is in use.
  * @param {!goog.math.Coordinate} newLoc The location to translate to, in
  *     workspace coordinates.

core/bubble_dragger.js

@@ -85,7 +85,7 @@ Blockly.BubbleDragger = function(bubble, workspace) {
   /**
    * The drag surface to move bubbles to during a drag, or null if none should
    * be used.  Block dragging and bubble dragging use the same surface.
-   * @type {?Blockly.BlockDragSurfaceSvg}
+   * @type {Blockly.BlockDragSurfaceSvg}
    * @private
    */
   this.dragSurface_ =

core/dropdowndiv.js

@@ -172,8 +172,8 @@ Blockly.DropDownDiv.clearContent = function() {
 
 /**
  * Set the colour for the drop-down.
- * @param {string} backgroundColour Any CSS color for the background
- * @param {string} borderColour Any CSS color for the border
+ * @param {string} backgroundColour Any CSS colour for the background.
+ * @param {string} borderColour Any CSS colour for the border.
  */
 Blockly.DropDownDiv.setColour = function(backgroundColour, borderColour) {
   Blockly.DropDownDiv.DIV_.style.backgroundColor = backgroundColour;
@@ -193,10 +193,12 @@ Blockly.DropDownDiv.setCategory = function(category) {
  * by a particular block. The primary position will be below the block,
  * and the secondary position above the block. Drop-down will be
  * constrained to the block's workspace.
- * @param {!Blockly.Field} field The field showing the drop-down
+ * @param {!Blockly.Field} field The field showing the drop-down.
  * @param {!Blockly.Block} block Block to position the drop-down around.
- * @param {Function=} opt_onHide Optional callback for when the drop-down is hidden.
- * @param {Number} opt_secondaryYOffset Optional Y offset for above-block positioning.
+ * @param {Function=} opt_onHide Optional callback for when the drop-down is
+ *   hidden.
+ * @param {number} opt_secondaryYOffset Optional Y offset for above-block
+ *   positioning.
  * @return {boolean} True if the menu rendered below block; false if above.
  */
 Blockly.DropDownDiv.showPositionedByBlock = function(field, block,
@@ -226,9 +228,11 @@ Blockly.DropDownDiv.showPositionedByBlock = function(field, block,
  * by a particular field. The primary position will be below the field,
  * and the secondary position above the field. Drop-down will be
  * constrained to the block's workspace.
- * @param {Object} owner The object showing the drop-down
- * @param {Function=} opt_onHide Optional callback for when the drop-down is hidden.
- * @param {Number} opt_secondaryYOffset Optional Y offset for above-block positioning.
+ * @param {Object} owner The object showing the drop-down.
+ * @param {Function=} opt_onHide Optional callback for when the drop-down is
+ *   hidden.
+ * @param {number} opt_secondaryYOffset Optional Y offset for above-block
+ *   positioning.
  * @return {boolean} True if the menu rendered below block; false if above.
  */
 Blockly.DropDownDiv.showPositionedByField = function(owner,
@@ -415,8 +419,8 @@ Blockly.DropDownDiv.isVisible = function() {
 
 /**
  * Hide the menu only if it is owned by the provided object.
- * @param {Object} owner Object which must be owning the drop-down to hide
- * @return {Boolean} True if hidden
+ * @param {Object} owner Object which must be owning the drop-down to hide.
+ * @return {boolean} True if hidden.
  */
 Blockly.DropDownDiv.hideIfOwner = function(owner) {
   if (Blockly.DropDownDiv.owner_ === owner) {

core/field.js

@@ -61,7 +61,7 @@ Blockly.Field.TYPE_MAP_ = {};
 /**
  * Registers a field type. May also override an existing field type.
  * Blockly.Field.fromJson uses this registry to find the appropriate field.
- * @param {!string} type The field type name as used in the JSON definition.
+ * @param {string} type The field type name as used in the JSON definition.
  * @param {!{fromJson: Function}} fieldClass The field class containing a
  *     fromJson function that can construct an instance of the field.
  * @throws {Error} if the type name is empty, or the fieldClass is not an
@@ -83,7 +83,7 @@ Blockly.Field.register = function(type, fieldClass) {
  * Blockly.Field.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
  */

core/field_angle.js

@@ -213,7 +213,7 @@ Blockly.FieldAngle.prototype.showEditor_ = function() {
   Blockly.DropDownDiv.showPositionedByField(this);
   // The angle picker is different from other fields in that it updates on
   // mousemove even if it's not in the middle of a drag.  In future we may
-  // change this behavior.  For now, using bindEvent_ instead of
+  // change this behaviour.  For now, using bindEvent_ instead of
   // bindEventWithChecks_ allows it to work without a mousedown/touchstart.
   this.clickWrapper_ =
       Blockly.bindEvent_(svg, 'click', this, this.hide_.bind(this));

core/field_variable.js

@@ -160,7 +160,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
  */

core/mutator.js

@@ -459,8 +459,8 @@ 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.
+ * @param {Blockly.Workspace} workspace The workspace that is inside a mutator.
+ * @return {Blockly.Workspace} The mutator's parent workspace or null.
  * @public
  */
 Blockly.Mutator.findParentWs = function(workspace) {

core/theme.js

@@ -26,9 +26,9 @@
 goog.provide('Blockly.Theme');
 /**
  * Class for a theme.
- * @param {?Object.<string, Blockly.BlockStyle>} blockStyles A map from style
+ * @param {Object.<string, Blockly.BlockStyle>} blockStyles A map from style
  *     names (strings) to objects with style attributes relating to blocks.
- * @param {?Object.<string, Blockly.CategoryStyle>} categoryStyles A map from
+ * @param {Object.<string, Blockly.CategoryStyle>} categoryStyles A map from
  *     style names (strings) to objects with style attributes relating to
  *     categories.
  * @constructor
@@ -59,7 +59,7 @@ Blockly.Theme.prototype.getAllBlockStyles = function() {
 
 /**
  * Gets the BlockStyle for the given block style name.
- * @param {String} blockStyleName The name of the block style.
+ * @param {string} blockStyleName The name of the block style.
  * @return {Blockly.BlockStyle} The style with the block style name.
  */
 Blockly.Theme.prototype.getBlockStyle = function(blockStyleName) {
@@ -68,7 +68,7 @@ Blockly.Theme.prototype.getBlockStyle = function(blockStyleName) {
 
 /**
  * Overrides or adds a style to the blockStyles map.
- * @param {String} blockStyleName The name of the block style.
+ * @param {string} blockStyleName The name of the block style.
  * @param {Blockly.BlockStyle} blockStyle The block style
 */
 Blockly.Theme.prototype.setBlockStyle = function(blockStyleName, blockStyle) {
@@ -77,7 +77,7 @@ Blockly.Theme.prototype.setBlockStyle = function(blockStyleName, blockStyle) {
 
 /**
  * Gets the CategoryStyle for the given category style name.
- * @param {String} categoryStyleName The name of the block style.
+ * @param {string} categoryStyleName The name of the block style.
  * @return {Blockly.CategoryStyle} The style with the block style name.
  */
 Blockly.Theme.prototype.getCategoryStyle = function(categoryStyleName) {
@@ -86,7 +86,7 @@ Blockly.Theme.prototype.getCategoryStyle = function(categoryStyleName) {
 
 /**
  * Overrides or adds a style to the categoryStyles map.
- * @param {String} categoryStyleName The name of the category style.
+ * @param {string} categoryStyleName The name of the category style.
  * @param {Blockly.CategoryStyle} categoryStyle The category style
 */
 Blockly.Theme.prototype.setCategoryStyle = function(categoryStyleName, categoryStyle) {

core/trashcan.js

@@ -401,7 +401,7 @@ Blockly.Trashcan.prototype.animateLid_ = function() {
 
 /**
  * Set the angle of the trashcan's lid.
- * @param {!number} lidAngle The angle at which to set the lid.
+ * @param {number} lidAngle The angle at which to set the lid.
  * @private
  */
 Blockly.Trashcan.prototype.setLidAngle_ = function(lidAngle) {
@@ -495,7 +495,7 @@ Blockly.Trashcan.prototype.onDelete_ = function() {
  *    content array.
  * @param {!Element} xml An XML tree defining the block and any
  *    connected child blocks.
- * @return {!string} Text representing the XML tree, cleaned of all unnecessary
+ * @return {string} Text representing the XML tree, cleaned of all unnecessary
  * attributes.
  * @private
  */

core/utils.js

@@ -433,8 +433,8 @@ Blockly.utils.tokenizeInterpolation = function(message) {
  * For example, "%{bky_my_msg}" and "%{BKY_MY_MSG}" will both be replaced with
  * the value in Blockly.Msg['MY_MSG'].
  * @param {string|?} message Message, which may be a string that contains
- *                           string table references.
- * @return {!string} String with message references replaced.
+ *     string table references.
+ * @return {string} String with message references replaced.
  */
 Blockly.utils.replaceMessageReferences = function(message) {
   if (typeof message != 'string') {
@@ -1032,10 +1032,10 @@ Blockly.utils.getBlockTypeCounts = function(block, opt_stripFollowing) {
 
 /**
  * Clamp the provided number between the lower bound and the upper bound.
- * @param {Number} lowerBound The desired lower bound.
- * @param {Number} number The number to clamp.
- * @param {Number} upperBound The desired upper bound.
- * @return {Number} The clamped number.
+ * @param {number} lowerBound The desired lower bound.
+ * @param {number} number The number to clamp.
+ * @param {number} upperBound The desired upper bound.
+ * @return {number} The clamped number.
  * @package
  */
 Blockly.utils.clampNumber = function(lowerBound, number, upperBound) {

core/variable_model.js

@@ -34,7 +34,7 @@ goog.require('Blockly.utils');
  * Class for a variable model.
  * Holds information for the variable including name, ID, and type.
  * @param {!Blockly.Workspace} workspace The variable's workspace.
- * @param {!string} name The name of the variable. This must be unique across
+ * @param {string} name The name of the variable. This must be unique across
  *     variables and procedures.
  * @param {string=} opt_type The type of the variable like 'int' or 'string'.
  *     Does not need to be unique. Field_variable can filter variables based on
@@ -81,7 +81,7 @@ Blockly.VariableModel = function(workspace, name, opt_type, opt_id) {
 };
 
 /**
- * @return {!string} The ID for the variable.
+ * @return {string} The ID for the variable.
  */
 Blockly.VariableModel.prototype.getId = function() {
   return this.id_;

core/variables.js

@@ -418,7 +418,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
  */
@@ -439,7 +439,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.
  * @private
  */
@@ -525,7 +525,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.
  * @package
  */

core/workspace.js

@@ -379,14 +379,14 @@ Blockly.Workspace.prototype.renameVariableById = function(id, newName) {
 
 /**
  * Create a variable with a given name, optional type, and optional ID.
- * @param {!string} name The name of the variable. This must be unique across
+ * @param {string} name The name of the variable. This must be unique across
  *     variables and procedures.
  * @param {string=} opt_type The type of the variable like 'int' or 'string'.
  *     Does not need to be unique. Field_variable can filter variables based on
  *     their type. This will default to '' which is a specific type.
  * @param {string=} opt_id The unique ID of the variable. This will default to
  *     a UUID.
- * @return {?Blockly.VariableModel} The newly created variable.
+ * @return {Blockly.VariableModel} The newly created variable.
  */
 Blockly.Workspace.prototype.createVariable = function(name, opt_type, opt_id) {
   return this.variableMap_.createVariable(name, opt_type, opt_id);
@@ -439,10 +439,10 @@ Blockly.Workspace.prototype.variableIndexOf = function(_name) {
 /**
  * Find the variable by the given name and return it. Return null if it is not
  *     found.
- * @param {!string} name The name to check for.
+ * @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 (#1199): Possibly delete this function.
 Blockly.Workspace.prototype.getVariable = function(name, opt_type) {
@@ -452,8 +452,8 @@ 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.
- * @param {!string} id The ID to check for.
- * @return {?Blockly.VariableModel} The variable with the given ID.
+ * @param {string} id The ID to check for.
+ * @return {Blockly.VariableModel} The variable with the given ID.
  */
 Blockly.Workspace.prototype.getVariableById = function(id) {
   return this.variableMap_.getVariableById(id);
@@ -622,8 +622,7 @@ Blockly.Workspace.prototype.clearUndo = function() {
  * new change listener might be called with events that occurred a few
  * milliseconds before the change listener was added.
  * @param {!Function} func Function to call.
- * @return {!Function} Function that can be passed to
- *     removeChangeListener.
+ * @return {!Function} Obsolete return value, ignore.
  */
 Blockly.Workspace.prototype.addChangeListener = function(func) {
   this.listeners_.push(func);
@@ -658,7 +657,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;
@@ -667,7 +666,7 @@ Blockly.Workspace.prototype.getBlockById = 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
  */
@@ -696,7 +695,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() {
@@ -713,7 +712,7 @@ Blockly.Workspace.prototype.createPotentialVariableMap = function() {
 
 /**
  * Return the map of all variables on the workspace.
- * @return {?Blockly.VariableMap} The  variable map.
+ * @return {Blockly.VariableMap} The variable map.
  */
 Blockly.Workspace.prototype.getVariableMap = function() {
   return this.variableMap_;

core/workspace_comment.js

@@ -100,7 +100,7 @@ Blockly.WorkspaceComment = function(workspace, content, height, width, opt_id) {
 
   /**
    * @protected
-   * @type {!string}
+   * @type {string}
    */
   this.content_ = content;
 
@@ -256,7 +256,7 @@ Blockly.WorkspaceComment.prototype.setContent = function(content) {
 
 /**
  * Encode a comment subtree as XML with XY coordinates.
- * @param {boolean=} opt_noId True if the encoder should skip the comment id.
+ * @param {boolean=} opt_noId True if the encoder should skip the comment ID.
  * @return {!Element} Tree of XML elements.
  * @package
  */
@@ -273,7 +273,7 @@ Blockly.WorkspaceComment.prototype.toXmlWithXY = function(opt_noId) {
  * Encode a comment subtree as XML, but don't serialize the XY coordinates.
  * This method avoids some expensive metrics-related calls that are made in
  * toXmlWithXY().
- * @param {boolean=} opt_noId True if the encoder should skip the comment id.
+ * @param {boolean=} opt_noId True if the encoder should skip the comment ID.
  * @return {!Element} Tree of XML elements.
  * @package
  */

core/workspace_comment_svg.js

@@ -377,7 +377,7 @@ Blockly.WorkspaceCommentSvg.prototype.moveOffDragSurface_ = function(newXY) {
 /**
  * Move this comment during a drag, taking into account whether we are using a
  * drag surface to translate blocks.
- * @param {?Blockly.BlockDragSurfaceSvg} dragSurface The surface that carries
+ * @param {Blockly.BlockDragSurfaceSvg} dragSurface The surface that carries
  *     rendered items during a drag, or null if no drag surface is in use.
  * @param {!goog.math.Coordinate} newLoc The location to translate to, in
  *     workspace coordinates.
@@ -576,7 +576,7 @@ Blockly.WorkspaceCommentSvg.fromXml = function(xmlComment, workspace,
 
 /**
  * Encode a comment subtree as XML with XY coordinates.
- * @param {boolean=} opt_noId True if the encoder should skip the comment id.
+ * @param {boolean=} opt_noId True if the encoder should skip the comment ID.
  * @return {!Element} Tree of XML elements.
  * @package
  */

core/workspace_drag_surface_svg.js

@@ -172,7 +172,7 @@ Blockly.WorkspaceDragSurfaceSvg.prototype.clearAndHide = function(newSurface) {
  * @param {!Element} blockCanvas The block canvas <g> element from the
  *     workspace.
  * @param {!Element} bubbleCanvas The <g> element that contains the bubbles.
- * @param {?Element} previousSibling The element to insert the block canvas &
+ * @param {Element} previousSibling The element to insert the block canvas and
        bubble canvas after when it goes back in the DOM at the end of a drag.
  * @param {number} width The width of the workspace SVG element.
  * @param {number} height The height of the workspace SVG element.

core/workspace_svg.js

@@ -354,7 +354,7 @@ Blockly.WorkspaceSvg.prototype.configureContextMenu = null;
 /**
  * In a flyout, the target workspace where blocks should be placed after a drag.
  * Otherwise null.
- * @type {?Blockly.WorkspaceSvg}
+ * @type {Blockly.WorkspaceSvg}
  * @package
  */
 Blockly.WorkspaceSvg.prototype.targetWorkspace = null;
@@ -892,7 +892,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
  */
@@ -1159,7 +1159,7 @@ Blockly.WorkspaceSvg.prototype.deleteVariableById = function(id) {
  *     their type. This will default to '' which is a specific type.
  * @param {string=} opt_id The unique ID of the variable. This will default to
  *     a UUID.
- * @return {?Blockly.VariableModel} The newly created variable.
+ * @return {Blockly.VariableModel} The newly created variable.
  * @package
  */
 Blockly.WorkspaceSvg.prototype.createVariable = function(name,

core/ws_comment_events.js

@@ -306,7 +306,7 @@ Blockly.Events.CommentMove = function(comment) {
   /**
    * The comment that is being moved.  Will be cleared after recording the new
    * location.
-   * @type {?Blockly.WorkspaceComment}
+   * @type {Blockly.WorkspaceComment}
    */
   this.comment_ = comment;
 

core/xml.js

@@ -100,7 +100,7 @@ Blockly.Xml.blockToDomWithXY = function(block, opt_noId) {
 /**
  * Encode a variable field as XML.
  * @param {!Blockly.FieldVariable} 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
  */
@@ -135,7 +135,7 @@ Blockly.Xml.fieldToDomVariable_ = function(field) {
 /**
  * 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
  */