JSDoc format fixes

core/block.js

@@ -46,7 +46,7 @@ goog.require('goog.string');
  * @param {!Blockly.Workspace} workspace The block's workspace.
  * @param {?string} prototypeName Name of the language object containing
  *     type-specific functions for this block.
- * @param {=string} opt_id Optional ID.  Use this ID if provided, otherwise
+ * @param {string=} opt_id Optional ID.  Use this ID if provided, otherwise
  *     create a new id.
  * @constructor
  */
@@ -1023,7 +1023,7 @@ Blockly.Block.prototype.jsonInit = function(json) {
  * @param {string} message Text contains interpolation tokens (%1, %2, ...)
  *     that match with fields or inputs defined in the args array.
  * @param {!Array} args Array of arguments to be interpolated.
- * @param {=string} lastDummyAlign If a dummy input is added at the end,
+ * @param {string=} lastDummyAlign If a dummy input is added at the end,
  *     how should it be aligned?
  * @private
  */

core/block_svg.js

@@ -43,7 +43,7 @@ goog.require('goog.userAgent');
  * @param {!Blockly.Workspace} workspace The block's workspace.
  * @param {?string} prototypeName Name of the language object containing
  *     type-specific functions for this block.
- * @param {=string} opt_id Optional ID.  Use this ID if provided, otherwise
+ * @param {string=} opt_id Optional ID.  Use this ID if provided, otherwise
  *     create a new id.
  * @extends {Blockly.Block}
  * @constructor

core/blockly.js

@@ -24,7 +24,10 @@
  */
 'use strict';
 
-// Top level object for Blockly.
+/**
+ * The top level namespace used to access the Blockly library.
+ * @namespace Blockly
+ */
 goog.provide('Blockly');
 
 goog.require('Blockly.BlockSvg.render');

core/events.js

@@ -24,6 +24,10 @@
  */
 'use strict';
 
+/**
+ * Events fired as a result of actions in Blockly's editor.
+ * @namespace Blockly.Events
+ */
 goog.provide('Blockly.Events');
 
 goog.require('goog.array');

core/flyout.js

@@ -111,13 +111,15 @@ Blockly.Flyout = function(workspaceOptions) {
 
   /**
    * y coordinate of mousedown - used to calculate scroll distances.
-   * @private {number}
+   * @type {number}
+   * @private
    */
   this.startDragMouseY_ = 0;
 
   /**
    * x coordinate of mousedown - used to calculate scroll distances.
-   * @private {number}
+   * @type {number}
+   * @private
    */
   this.startDragMouseX_ = 0;
 };
@@ -125,40 +127,46 @@ Blockly.Flyout = function(workspaceOptions) {
 /**
  * When a flyout drag is in progress, this is a reference to the flyout being
  * dragged. This is used by Flyout.terminateDrag_ to reset dragMode_.
- * @private {Blockly.Flyout}
+ * @type {Blockly.Flyout}
+ * @private
  */
 Blockly.Flyout.startFlyout_ = null;
 
 /**
  * Event that started a drag. Used to determine the drag distance/direction and
  * also passed to BlockSvg.onMouseDown_() after creating a new block.
- * @private {Event}
+ * @type {Event}
+ * @private
  */
 Blockly.Flyout.startDownEvent_ = null;
 
 /**
  * Flyout block where the drag/click was initiated. Used to fire click events or
  * create a new block.
- * @private {Event}
+ * @type {Event}
+ * @private
  */
 Blockly.Flyout.startBlock_ = null;
 
 /**
  * Wrapper function called when a mouseup occurs during a background or block
  * drag operation.
- * @private {Array.<!Array>}
+ * @type {Array.<!Array>}
+ * @private
  */
 Blockly.Flyout.onMouseUpWrapper_ = null;
 
 /**
  * Wrapper function called when a mousemove occurs during a background drag.
- * @private {Array.<!Array>}
+ * @type {Array.<!Array>}
+ * @private
  */
 Blockly.Flyout.onMouseMoveWrapper_ = null;
 
 /**
  * Wrapper function called when a mousemove occurs during a block drag.
- * @private {Array.<!Array>}
+ * @type {Array.<!Array>}
+ * @private
  */
 Blockly.Flyout.onMouseMoveBlockWrapper_ = null;
 

core/options.js

@@ -127,8 +127,8 @@ Blockly.Options = function(options) {
 };
 
 /**
- * @type {Blockly.Workspace} the parent of the current workspace, or null if
- *    there is no parent workspace.
+ * The parent of the current workspace, or null if there is no parent workspace.
+ * @type {Blockly.Workspace}
  **/
 Blockly.Options.prototype.parentWorkspace = null;
 

core/workspace.js

@@ -83,14 +83,14 @@ Blockly.Workspace = function(opt_options) {
 };
 
 /**
- * Workspaces may be headless.
- * @type {boolean} True if visible.  False if headless.
+ * Returns `true` if the workspace is visible and `false` if it's headless.
+ * @type {boolean}
  */
 Blockly.Workspace.prototype.rendered = false;
 
 /**
- * Maximum number of undo events in stack.
- * @type {number} 0 to turn off undo, Infinity for unlimited.
+ * Maximum number of undo events in stack. `0` turns off undo, `Infinity` sets it to unlimited.
+ * @type {number}
  */
 Blockly.Workspace.prototype.MAX_UNDO = 1024;
 
@@ -362,7 +362,7 @@ Blockly.Workspace.prototype.getWidth = function() {
  * Obtain a newly created block.
  * @param {?string} prototypeName Name of the language object containing
  *     type-specific functions for this block.
- * @param {=string} opt_id Optional ID.  Use this ID if provided, otherwise
+ * @param {string=} opt_id Optional ID.  Use this ID if provided, otherwise
  *     create a new id.
  * @return {!Blockly.Block} The created block.
  */

core/workspace_svg.js

@@ -69,14 +69,15 @@ Blockly.WorkspaceSvg = function(options) {
 goog.inherits(Blockly.WorkspaceSvg, Blockly.Workspace);
 
 /**
- * Wrapper function called when a resize event occurs.
- * @type {Array.<!Array>} Data that can be passed to unbindEvent_
+ * A wrapper function called when a resize event occurs. You can pass the result to `unbindEvent_`.
+ * @type {Array.<!Array>}
  */
 Blockly.WorkspaceSvg.prototype.resizeHandlerWrapper_ = null;
 
 /**
- * Svg workspaces are user-visible (as opposed to a headless workspace).
- * @type {boolean} True if visible.  False if headless.
+ * The render status of an SVG workspace. 
+ * Returns `true` for visible workspaces and `false` for non-visible, or headless, workspaces. 
+ * @type {boolean}
  */
 Blockly.WorkspaceSvg.prototype.rendered = true;
 
@@ -314,7 +315,7 @@ Blockly.WorkspaceSvg.prototype.dispose = function() {
  * Obtain a newly created block.
  * @param {?string} prototypeName Name of the language object containing
  *     type-specific functions for this block.
- * @param {=string} opt_id Optional ID.  Use this ID if provided, otherwise
+ * @param {string=} opt_id Optional ID.  Use this ID if provided, otherwise
  *     create a new id.
  * @return {!Blockly.BlockSvg} The created block.
  */