Adding more type documentation.

appengine/storage.js

@@ -43,7 +43,7 @@ BlocklyStorage.backupBlocks_ = function(workspace) {
 
 /**
  * Bind the localStorage backup function to the unload event.
- * @param {Blockly.WorkspaceSvg} opt_workspace Workspace.
+ * @param {Blockly.WorkspaceSvg=} opt_workspace Workspace.
  */
 BlocklyStorage.backupOnUnload = function(opt_workspace) {
   var workspace = opt_workspace || Blockly.getMainWorkspace();
@@ -53,7 +53,7 @@ BlocklyStorage.backupOnUnload = function(opt_workspace) {
 
 /**
  * Restore code blocks from localStorage.
- * @param {Blockly.WorkspaceSvg} opt_workspace Workspace.
+ * @param {Blockly.WorkspaceSvg=} opt_workspace Workspace.
  */
 BlocklyStorage.restoreBlocks = function(opt_workspace) {
   var url = window.location.href.split('#')[0];
@@ -66,7 +66,7 @@ BlocklyStorage.restoreBlocks = function(opt_workspace) {
 
 /**
  * Save blocks to database and return a link containing key to XML.
- * @param {Blockly.WorkspaceSvg} opt_workspace Workspace.
+ * @param {Blockly.WorkspaceSvg=} opt_workspace Workspace.
  */
 BlocklyStorage.link = function(opt_workspace) {
   var workspace = opt_workspace || Blockly.getMainWorkspace();
@@ -78,7 +78,7 @@ BlocklyStorage.link = function(opt_workspace) {
 /**
  * Retrieve XML text from database using given key.
  * @param {string} key Key to XML, obtained from href.
- * @param {Blockly.WorkspaceSvg} opt_workspace Workspace.
+ * @param {Blockly.WorkspaceSvg=} opt_workspace Workspace.
  */
 BlocklyStorage.retrieveXml = function(key, opt_workspace) {
   var workspace = opt_workspace || Blockly.getMainWorkspace();
@@ -87,7 +87,7 @@ BlocklyStorage.retrieveXml = function(key, opt_workspace) {
 
 /**
  * Global reference to current AJAX request.
- * @type XMLHttpRequest
+ * @type {XMLHttpRequest}
  * @private
  */
 BlocklyStorage.httpRequest_ = null;

core/block.js

@@ -90,38 +90,45 @@ Blockly.Block.prototype.initialize = function(workspace, prototypeName) {
  * @param {string} prototypeName The typename of the block.
  */
 Blockly.Block.prototype.fill = function(workspace, prototypeName) {
-  /** @type {?Blockly.Connection} */
+  /** @type {Blockly.Connection} */
   this.outputConnection = null;
-  /** @type {?Blockly.Connection} */
+  /** @type {Blockly.Connection} */
   this.nextConnection = null;
-  /** @type {?Blockly.Connection} */
+  /** @type {Blockly.Connection} */
   this.previousConnection = null;
-  /** @type {Blockly.Input[]} */
+  /** @type {!Array.<!Blockly.Input>} */
   this.inputList = [];
-  /** @type {?boolean} */
+  /** @type {boolean|undefined} */
   this.inputsInline = undefined;
   /** @type {boolean} */
   this.rendered = false;
   /** @type {boolean} */
   this.disabled = false;
-  /** @type {(string|Function|object)} */
+  /** @type {string|!Function} */
   this.tooltip = '';
   /** @type {boolean} */
   this.contextMenu = true;
 
+  /** @type {Blockly.Block} */
   this.parentBlock_ = null;
+  /** @type {!Array.<!Blockly.Block>} */
   this.childBlocks_ = [];
+  /** @type {boolean} */
   this.deletable_ = true;
+  /** @type {boolean} */
   this.movable_ = true;
+  /** @type {boolean} */
   this.editable_ = true;
+  /** @type {boolean} */
   this.collapsed_ = false;
 
-  /** @type {?(string|Blockly.Comment)} */
+  /** @type {string|Blockly.Comment} */
   this.comment = null;
 
+  /** @type {!goog.math.Coordinate} */
   this.xy_ = new goog.math.Coordinate(0, 0);
 
-  /** @type {Blockly.Workspace} */
+  /** @type {!Blockly.Workspace} */
   this.workspace = workspace;
   /** @type {boolean} */
   this.isInFlyout = workspace.isFlyout;
@@ -130,7 +137,7 @@ Blockly.Block.prototype.fill = function(workspace, prototypeName) {
 
   // Copy the type-specific functions and data from the prototype.
   if (prototypeName) {
-    /** @type {?string} */
+    /** @type {string} */
     this.type = prototypeName;
     var prototype = Blockly.Blocks[prototypeName];
     goog.asserts.assertObject(prototype,
@@ -142,6 +149,7 @@ Blockly.Block.prototype.fill = function(workspace, prototypeName) {
     this.init();
   }
   // Record initial inline state.
+  /** @type {boolean|undefined} */
   this.inputsInlineDefault = this.inputsInline;
 };
 
@@ -165,7 +173,7 @@ Blockly.Block.getById = function(id, workspace) {
  *     the next statement with the previous statement.  Otherwise, dispose of
  *     all children of this block.
  * @param {boolean} animate If true, show a disposal animation and sound.
- * @param {boolean} opt_dontRemoveFromWorkspace If true, don't remove this
+ * @param {boolean=} opt_dontRemoveFromWorkspace If true, don't remove this
  *     block from the workspace's list of top blocks.
  */
 Blockly.Block.prototype.dispose = function(healStack, animate,
@@ -667,8 +675,8 @@ Blockly.Block.prototype.setTitleValue = function(newValue, name) {
 /**
  * Set whether this block can chain onto the bottom of another block.
  * @param {boolean} newBoolean True if there can be a previous statement.
- * @param {string|Array.<string>|null} opt_check Statement type or list of
- *     statement types.  Null or undefined if any type could be connected.
+ * @param {string|Array.<string>|null|undefined} opt_check Statement type or
+ *     list of statement types.  Null/undefined if any type could be connected.
  */
 Blockly.Block.prototype.setPreviousStatement = function(newBoolean, opt_check) {
   if (this.previousConnection) {
@@ -696,8 +704,8 @@ Blockly.Block.prototype.setPreviousStatement = function(newBoolean, opt_check) {
 /**
  * Set whether another block can chain onto the bottom of this block.
  * @param {boolean} newBoolean True if there can be a next statement.
- * @param {string|Array.<string>|null} opt_check Statement type or list of
- *     statement types.  Null or undefined if any type could be connected.
+ * @param {string|Array.<string>|null|undefined} opt_check Statement type or
+ *     list of statement types.  Null/undefined if any type could be connected.
  */
 Blockly.Block.prototype.setNextStatement = function(newBoolean, opt_check) {
   if (this.nextConnection) {
@@ -723,8 +731,8 @@ Blockly.Block.prototype.setNextStatement = function(newBoolean, opt_check) {
 /**
  * Set whether this block returns a value.
  * @param {boolean} newBoolean True if there is an output.
- * @param {string|Array.<string>|null} opt_check Returned type or list of
- *     returned types.  Null or undefined if any type could be returned
+ * @param {string|Array.<string>|null|undefined} opt_check Returned type or list
+ *     of returned types.  Null or undefined if any type could be returned
  *     (e.g. variable get).
  */
 Blockly.Block.prototype.setOutput = function(newBoolean, opt_check) {
@@ -848,7 +856,7 @@ Blockly.Block.prototype.setCollapsed = function(collapsed) {
 
 /**
  * Create a human-readable text representation of this block and any children.
- * @param {?number} opt_maxLength Truncate the string to this length.
+ * @param {number=} opt_maxLength Truncate the string to this length.
  * @return {string} Text of block.
  */
 Blockly.Block.prototype.toString = function(opt_maxLength) {
@@ -901,7 +909,7 @@ Blockly.Block.prototype.appendStatementInput = function(name) {
 
 /**
  * Shortcut for appending a dummy input row.
- * @param {string} opt_name Language-neutral identifier which may used to find
+ * @param {string=} opt_name Language-neutral identifier which may used to find
  *     this input again.  Should be unique to this block.
  * @return {!Blockly.Input} The input object created.
  */
@@ -1171,7 +1179,7 @@ Blockly.Block.prototype.moveNumberedInputBefore = function(
 /**
  * Remove an input from this block.
  * @param {string} name The name of the input.
- * @param {boolean} opt_quiet True to prevent error if input is not present.
+ * @param {boolean=} opt_quiet True to prevent error if input is not present.
  * @throws {goog.asserts.AssertionError} if the input is not present and
  *     opt_quiet is not true.
  */

core/block_svg.js

@@ -981,7 +981,7 @@ Blockly.BlockSvg.INNER_BOTTOM_LEFT_CORNER_HIGHLIGHT_LTR =
  *     the next statement with the previous statement.  Otherwise, dispose of
  *     all children of this block.
  * @param {boolean} animate If true, show a disposal animation and sound.
- * @param {boolean} opt_dontRemoveFromWorkspace If true, don't remove this
+ * @param {boolean=} opt_dontRemoveFromWorkspace If true, don't remove this
  *     block from the workspace's list of top blocks.
  */
 Blockly.BlockSvg.prototype.dispose = function(healStack, animate,
@@ -1319,7 +1319,7 @@ Blockly.BlockSvg.prototype.removeDragging = function() {
 /**
  * Render the block.
  * Lays out and reflows a block based on its contents and settings.
- * @param {boolean} opt_bubble If false, just render this block.
+ * @param {boolean=} opt_bubble If false, just render this block.
  *   If true, also render block's parent, grandparent, etc.  Defaults to true.
  */
 Blockly.BlockSvg.prototype.render = function(opt_bubble) {

core/css.js

@@ -41,21 +41,21 @@ Blockly.Css.Cursor = {
 
 /**
  * Current cursor (cached value).
- * @type string
+ * @type {string}
  * @private
  */
 Blockly.Css.currentCursor_ = '';
 
 /**
  * Large stylesheet added by Blockly.Css.inject.
- * @type Element
+ * @type {Element}
  * @private
  */
 Blockly.Css.styleSheet_ = null;
 
 /**
  * Path to media directory, with any trailing slash removed.
- * @type string
+ * @type {string}
  * @private
  */
 Blockly.Css.mediaPath_ = '';

core/field_angle.js

@@ -34,7 +34,7 @@ goog.require('goog.userAgent');
 /**
  * Class for an editable angle field.
  * @param {string} text The initial content of the field.
- * @param {Function} opt_changeHandler An optional function that is called
+ * @param {Function=} opt_changeHandler An optional function that is called
  *     to validate any constraints on what the user entered.  Takes the new
  *     text as an argument and returns the accepted text or null to abort
  *     the change.

core/field_checkbox.js

@@ -32,7 +32,7 @@ goog.require('Blockly.Field');
 /**
  * Class for a checkbox field.
  * @param {string} state The initial state of the field ('TRUE' or 'FALSE').
- * @param {Function} opt_changeHandler A function that is executed when a new
+ * @param {Function=} opt_changeHandler A function that is executed when a new
  *     option is selected.  Its sole argument is the new checkbox state.  If
  *     it returns a value, this becomes the new checkbox state, unless the
  *     value is null, in which case the change is aborted.

core/field_colour.js

@@ -36,7 +36,7 @@ goog.require('goog.ui.ColorPicker');
 /**
  * Class for a colour input field.
  * @param {string} colour The initial colour in '#rrggbb' format.
- * @param {Function} opt_changeHandler A function that is executed when a new
+ * @param {Function=} opt_changeHandler A function that is executed when a new
  *     colour is selected.  Its sole argument is the new colour value.  Its
  *     return value becomes the selected colour, unless it is undefined, in
  *     which case the new colour stands, or it is null, in which case the change

core/field_date.js

@@ -39,7 +39,7 @@ goog.require('goog.ui.DatePicker');
 /**
  * Class for a date input field.
  * @param {string} date The initial date.
- * @param {Function} opt_changeHandler A function that is executed when a new
+ * @param {Function=} opt_changeHandler A function that is executed when a new
  *     date is selected.  Its sole argument is the new date value.  Its
  *     return value becomes the selected date, unless it is undefined, in
  *     which case the new date stands, or it is null, in which case the change

core/field_dropdown.js

@@ -41,7 +41,7 @@ goog.require('goog.userAgent');
  * Class for an editable dropdown field.
  * @param {(!Array.<!Array.<string>>|!Function)} menuGenerator An array of options
  *     for a dropdown list, or a function which generates these options.
- * @param {Function} opt_changeHandler A function that is executed when a new
+ * @param {Function=} opt_changeHandler A function that is executed when a new
  *     option is selected, with the newly selected value as its sole argument.
  *     If it returns a value, that value (which must be one of the options) will
  *     become selected in place of the newly selected option, unless the return

core/field_image.js

@@ -36,7 +36,7 @@ goog.require('goog.userAgent');
  * @param {string} src The URL of the image.
  * @param {number} width Width of the image.
  * @param {number} height Height of the image.
- * @param {?string} opt_alt Optional alt text for when block is collapsed.
+ * @param {string=} opt_alt Optional alt text for when block is collapsed.
  * @extends {Blockly.Field}
  * @constructor
  */

core/field_textinput.js

@@ -36,7 +36,7 @@ goog.require('goog.userAgent');
 /**
  * Class for an editable text field.
  * @param {string} text The initial content of the field.
- * @param {Function} opt_changeHandler An optional function that is called
+ * @param {Function=} opt_changeHandler An optional function that is called
  *     to validate any constraints on what the user entered.  Takes the new
  *     text as an argument and returns either the accepted text, a replacement
  *     text, or null to abort the change.

core/field_variable.js

@@ -36,7 +36,7 @@ goog.require('goog.string');
  * Class for a variable's dropdown field.
  * @param {?string} varname The default name for the variable.  If null,
  *     a unique variable name will be generated.
- * @param {Function} opt_changeHandler A function that is executed when a new
+ * @param {Function=} opt_changeHandler A function that is executed when a new
  *     option is selected.  Its sole argument is the new option value.
  * @extends {Blockly.FieldDropdown}
  * @constructor

core/generator.js

@@ -51,7 +51,7 @@ Blockly.Generator.NAME_TYPE = 'generated_function';
  * Arbitrary code to inject into locations that risk causing infinite loops.
  * Any instances of '%1' will be replaced by the block ID that failed.
  * E.g. '  checkTimeout(%1);\n'
- * @type ?string
+ * @type {?string}
  */
 Blockly.Generator.prototype.INFINITE_LOOP_TRAP = null;
 
@@ -59,7 +59,7 @@ Blockly.Generator.prototype.INFINITE_LOOP_TRAP = null;
  * Arbitrary code to inject before every statement.
  * Any instances of '%1' will be replaced by the block ID of the statement.
  * E.g. 'highlight(%1);\n'
- * @type ?string
+ * @type {?string}
  */
 Blockly.Generator.prototype.STATEMENT_PREFIX = null;
 

core/inject.js

@@ -36,7 +36,7 @@ goog.require('goog.userAgent');
 /**
  * Inject a Blockly editor into the specified container element (usually a div).
  * @param {!Element|string} container Containing element or its ID.
- * @param {Object} opt_options Optional dictionary of options.
+ * @param {Object=} opt_options Optional dictionary of options.
  * @return {!Blockly.Workspace} Newly created main workspace.
  */
 Blockly.inject = function(container, opt_options) {

core/input.js

@@ -61,7 +61,7 @@ Blockly.Input = function(type, name, block, connection) {
 /**
  * Add an item to the end of the input's field row.
  * @param {string|!Blockly.Field} field Something to add as a field.
- * @param {string} opt_name Language-neutral identifier which may used to find
+ * @param {string=} opt_name Language-neutral identifier which may used to find
  *     this field again.  Should be unique to the host block.
  * @return {!Blockly.Input} The input being append to (to allow chaining).
  */
@@ -101,7 +101,7 @@ Blockly.Input.prototype.appendField = function(field, opt_name) {
 /**
  * Add an item to the end of the input's field row.
  * @param {*} field Something to add as a field.
- * @param {string} opt_name Language-neutral identifier which may used to find
+ * @param {string=} opt_name Language-neutral identifier which may used to find
  *     this field again.  Should be unique to the host block.
  * @return {!Blockly.Input} The input being append to (to allow chaining).
  * @deprecated December 2013

core/msg.js

@@ -32,7 +32,7 @@ goog.provide('Blockly.Msg');
 
 /**
  * Back up original getMsg function.
- * @type !Function
+ * @type {!Function}
  */
 goog.getMsgOrig = goog.getMsg;
 

core/procedures.js

@@ -117,7 +117,7 @@ Blockly.Procedures.findLegalName = function(name, block) {
  * procedures already defined.
  * @param {string} name The questionable name.
  * @param {!Blockly.Workspace} workspace The workspace to scan for collisions.
- * @param {Blockly.Block} opt_exclude Optional block to exclude from
+ * @param {Blockly.Block=} opt_exclude Optional block to exclude from
  *     comparisons (one doesn't want to collide with oneself).
  * @return {boolean} True if the name is legal.
  */

core/scrollbar.js

@@ -144,7 +144,7 @@ Blockly.ScrollbarPair.prototype.set = function(x, y) {
  * look or behave like the system's scrollbars.
  * @param {!Blockly.Workspace} workspace Workspace to bind the scrollbar to.
  * @param {boolean} horizontal True if horizontal, false if vertical.
- * @param {boolean} opt_pair True if the scrollbar is part of a horiz/vert pair.
+ * @param {boolean=} opt_pair True if the scrollbar is part of a horiz/vert pair.
  * @constructor
  */
 Blockly.Scrollbar = function(workspace, horizontal, opt_pair) {

core/tooltip.js

@@ -108,7 +108,7 @@ Blockly.Tooltip.MARGINS = 5;
 
 /**
  * The HTML container.  Set once by Blockly.Tooltip.createDom.
- * @type Element
+ * @type {Element}
  */
 Blockly.Tooltip.DIV = null;
 

core/utils.js

@@ -395,7 +395,7 @@ Blockly.shortestStringLength = function(array) {
  * Given an array of strings, return the length of the common prefix.
  * Words may not be split.  Any space after a word is included in the length.
  * @param {!Array.<string>} array Array of strings.
- * @param {?number} opt_shortest Length of shortest string.
+ * @param {number=} opt_shortest Length of shortest string.
  * @return {number} Length of common prefix.
  */
 Blockly.commonWordPrefix = function(array, opt_shortest) {
@@ -430,7 +430,7 @@ Blockly.commonWordPrefix = function(array, opt_shortest) {
  * Given an array of strings, return the length of the common suffix.
  * Words may not be split.  Any space after a word is included in the length.
  * @param {!Array.<string>} array Array of strings.
- * @param {?number} opt_shortest Length of shortest string.
+ * @param {number=} opt_shortest Length of shortest string.
  * @return {number} Length of common suffix.
  */
 Blockly.commonWordSuffix = function(array, opt_shortest) {

core/widgetdiv.js

@@ -34,21 +34,21 @@ goog.require('goog.dom');
 
 /**
  * The HTML container.  Set once by Blockly.WidgetDiv.createDom.
- * @type Element
+ * @type {Element}
  */
 Blockly.WidgetDiv.DIV = null;
 
 /**
  * The object currently using this container.
  * @private
- * @type Object
+ * @type {Object}
  */
 Blockly.WidgetDiv.owner_ = null;
 
 /**
  * Optional cleanup function set by whichever object uses the widget.
  * @private
- * @type Function
+ * @type {Function}
  */
 Blockly.WidgetDiv.dispose_ = null;
 

core/workspace.js

@@ -32,7 +32,7 @@ goog.require('goog.math');
 /**
  * Class for a workspace.  This is a data structure that contains blocks.
  * There is no UI, and can be created headlessly.
- * @param {Object} opt_options Dictionary of options.
+ * @param {Object=} opt_options Dictionary of options.
  * @constructor
  */
 Blockly.Workspace = function(opt_options) {

core/workspace_svg.js

@@ -645,7 +645,7 @@ Blockly.WorkspaceSvg.prototype.preloadAudio_ = function() {
  * Play an audio file at specified value.  If volume is not specified,
  * use full volume (1).
  * @param {string} name Name of sound.
- * @param {?number} opt_volume Volume of sound (0-1).
+ * @param {number=} opt_volume Volume of sound (0-1).
  */
 Blockly.WorkspaceSvg.prototype.playAudio = function(name, opt_volume) {
   var sound = this.SOUNDS_[name];

demos/blockfactory/factory.js

@@ -25,13 +25,13 @@
 
 /**
  * Workspace for user to build block.
- * @type Blockly.Workspace
+ * @type {Blockly.Workspace}
  */
 var mainWorkspace = null;
 
 /**
  * Workspace for preview of block.
- * @type Blockly.Workspace
+ * @type {Blockly.Workspace}
  */
 var previewWorkspace = null;
 

demos/code/code.js

@@ -82,7 +82,7 @@ Code.LANGUAGE_RTL = ['ar', 'fa', 'he'];
 
 /**
  * Blockly's main workspace.
- * @type Blockly.WorkspaceSvg
+ * @type {Blockly.WorkspaceSvg}
  */
 Code.workspace = null;
 
@@ -235,7 +235,7 @@ Code.getBBox_ = function(element) {
 
 /**
  * User's language (e.g. "en").
- * @type string
+ * @type {string}
  */
 Code.LANG = Code.getLang();
 

demos/graph/index.html

@@ -176,20 +176,20 @@ var Graph = {};
 
 /**
  * Main Blockly workspace.
- * @type Blockly.WorkspaceSvg
+ * @type {Blockly.WorkspaceSvg}
  */
 Graph.workspace = null;
 
 /**
  * Cached copy of the function string.
- * @type ?string
+ * @type {?string}
  * @private
  */
 Graph.oldFormula_ = null;
 
 /**
  * Drawing options for the Chart API.
- * @type !Object
+ * @type {!Object}
  * @private
  */
 Graph.options_ = {

demos/plane/plane.js

@@ -76,7 +76,7 @@ Plane.LANGUAGE_RTL = ['ar', 'fa', 'he'];
 
 /**
  * Main Blockly workspace.
- * @type Blockly.WorkspaceSvg
+ * @type {Blockly.WorkspaceSvg}
  */
 Plane.workspace = null;
 
@@ -201,7 +201,7 @@ Plane.getMsg = function(key) {
 
 /**
  * User's language (e.g. "en").
- * @type string
+ * @type {string}
  */
 Plane.LANG = Plane.getLang();
 

demos/plane/slider.js

@@ -30,7 +30,7 @@
  * @param {number} y The vertical offset of the slider.
  * @param {number} width The total width of the slider.
  * @param {!Element} svgParent The SVG element to append the slider to.
- * @param {Function} opt_changeFunc Optional callback function that will be
+ * @param {Function=} opt_changeFunc Optional callback function that will be
  *     called when the slider is moved.  The current value is passed.
  * @constructor
  */

generators/dart.js

@@ -31,7 +31,7 @@ goog.require('Blockly.Generator');
 
 /**
  * Dart code generator.
- * @type !Blockly.Generator
+ * @type {!Blockly.Generator}
  */
 Blockly.Dart = new Blockly.Generator('Dart');
 

generators/javascript.js

@@ -31,7 +31,7 @@ goog.require('Blockly.Generator');
 
 /**
  * JavaScript code generator.
- * @type !Blockly.Generator
+ * @type {!Blockly.Generator}
  */
 Blockly.JavaScript = new Blockly.Generator('JavaScript');
 

generators/php.js

@@ -31,7 +31,7 @@ goog.require('Blockly.Generator');
 
 /**
  * PHP code generator.
- * @type !Blockly.Generator
+ * @type {!Blockly.Generator}
  */
 Blockly.PHP = new Blockly.Generator('PHP');
 

generators/python.js

@@ -31,7 +31,7 @@ goog.require('Blockly.Generator');
 
 /**
  * Python code generator.
- * @type !Blockly.Generator
+ * @type {!Blockly.Generator}
  */
 Blockly.Python = new Blockly.Generator('Python');