From 97644fdf040a2cfe435f11ed25fba0e62287da96 Mon Sep 17 00:00:00 2001
From: Neil Fraser <fraser@google.com>
Date: Sat, 3 Dec 2016 06:34:18 -0800
Subject: [PATCH] Improve comments.

---
 core/block_svg.js     |  3 ++-
 core/workspace_svg.js | 12 ++++++++----
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/core/block_svg.js b/core/block_svg.js
index 4133b6fdc..4bc170d53 100644
--- a/core/block_svg.js
+++ b/core/block_svg.js
@@ -1510,7 +1510,8 @@ Blockly.BlockSvg.prototype.setDisabled = function(disabled) {
 };
 
 /**
- * Set whether the block is highlighted or not.
+ * Set whether the block is highlighted or not.  Block highlighting is
+ * often used to visually mark blocks currently being executed.
  * @param {boolean} highlighted True if highlighted.
  */
 Blockly.BlockSvg.prototype.setHighlighted = function(highlighted) {
diff --git a/core/workspace_svg.js b/core/workspace_svg.js
index fa55f51aa..bd1a75a0e 100644
--- a/core/workspace_svg.js
+++ b/core/workspace_svg.js
@@ -73,7 +73,8 @@ Blockly.WorkspaceSvg = function(options, opt_blockDragSurface) {
    */
   this.SOUNDS_ = Object.create(null);
   /**
-   * List of currently highlighted blocks.
+   * List of currently highlighted blocks.  Block highlighting is often used to
+   * visually mark blocks currently being executed.
    * @type !Array.<!Blockly.BlockSvg>
    * @private
    */
@@ -82,14 +83,16 @@ Blockly.WorkspaceSvg = function(options, opt_blockDragSurface) {
 goog.inherits(Blockly.WorkspaceSvg, Blockly.Workspace);
 
 /**
- * A wrapper function called when a resize event occurs. You can pass the result 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;
 
 /**
  * The render status of an SVG workspace.
- * Returns `true` for visible workspaces and `false` for non-visible, or headless, workspaces.
+ * Returns `true` for visible workspaces and `false` for non-visible,
+ * or headless, workspaces.
  * @type {boolean}
  */
 Blockly.WorkspaceSvg.prototype.rendered = true;
@@ -613,7 +616,8 @@ Blockly.WorkspaceSvg.prototype.traceOn = function() {
 };
 
 /**
- * Highlight or unhighlight a block in the workspace.
+ * Highlight or unhighlight a block in the workspace.  Block highlighting is
+ * often used to visually mark blocks currently being executed.
  * @param {?string} id ID of block to highlight/unhighlight,
  *   or null for no block (used to unhighlight all blocks).
  * @param {boolean=} opt_state If undefined, highlight specified block and