Merge pull request #1025 from rachel-fenichel/cleanup/misc

Miscellaneous comment cleanup

core/block.js

@@ -119,6 +119,8 @@ Blockly.Block = function(workspace, prototypeName, opt_id) {
   this.comment = null;
 
   /**
+   * The block's position in workspace units.  (0, 0) is at the workspace's
+   * origin; scale does not change this value.
    * @type {!goog.math.Coordinate}
    * @private
    */
@@ -1445,7 +1447,7 @@ Blockly.Block.prototype.setMutator = function(/* mutator */) {
 
 /**
  * Return the coordinates of the top-left corner of this block relative to the
- * drawing surface's origin (0,0).
+ * drawing surface's origin (0,0), in workspace units.
  * @return {!goog.math.Coordinate} Object with .x and .y properties.
  */
 Blockly.Block.prototype.getRelativeToSurfaceXY = function() {
@@ -1454,8 +1456,8 @@ Blockly.Block.prototype.getRelativeToSurfaceXY = function() {
 
 /**
  * Move a block by a relative offset.
- * @param {number} dx Horizontal offset.
- * @param {number} dy Vertical offset.
+ * @param {number} dx Horizontal offset, in workspace units.
+ * @param {number} dy Vertical offset, in workspace units.
  */
 Blockly.Block.prototype.moveBy = function(dx, dy) {
   goog.asserts.assert(!this.parentBlock_, 'Block has parent.');

core/block_drag_surface.js

@@ -112,10 +112,10 @@ Blockly.BlockDragSurfaceSvg.prototype.setBlocksAndShow = function(blocks) {
 };
 
 /**
- * Translate and scale the entire drag surface group to keep in sync with the
- * workspace.
- * @param {number} x X translation
- * @param {number} y Y translation
+ * Translate and scale the entire drag surface group to the given position, to
+ * keep in sync with the workspace.
+ * @param {number} x X translation in workspace coordinates.
+ * @param {number} y Y translation in workspace coordinates.
  * @param {number} scale Scale of the group.
  */
 Blockly.BlockDragSurfaceSvg.prototype.translateAndScaleGroup = function(x, y, scale) {

core/block_svg.js

@@ -99,10 +99,12 @@ goog.inherits(Blockly.BlockSvg, Blockly.Block);
 
 /**
  * Height of this block, not including any statement blocks above or below.
+ * Height is in workspace units.
  */
 Blockly.BlockSvg.prototype.height = 0;
 /**
  * Width of this block, including any connected value blocks.
+ * Width is in workspace units.
  */
 Blockly.BlockSvg.prototype.width = 0;
 
@@ -324,8 +326,10 @@ Blockly.BlockSvg.prototype.setParent = function(newParent) {
 
 /**
  * Return the coordinates of the top-left corner of this block relative to the
- * drawing surface's origin (0,0).
- * @return {!goog.math.Coordinate} Object with .x and .y properties.
+ * drawing surface's origin (0,0), in workspace units.
+ * This does not change with workspace scale.
+ * @return {!goog.math.Coordinate} Object with .x and .y properties in
+ *     workspace coordinates.
  */
 Blockly.BlockSvg.prototype.getRelativeToSurfaceXY = function() {
   var x = 0;
@@ -358,8 +362,8 @@ Blockly.BlockSvg.prototype.getRelativeToSurfaceXY = function() {
 
 /**
  * Move a block by a relative offset.
- * @param {number} dx Horizontal offset.
- * @param {number} dy Vertical offset.
+ * @param {number} dx Horizontal offset in workspace units.
+ * @param {number} dy Vertical offset in workspace units.
  */
 Blockly.BlockSvg.prototype.moveBy = function(dx, dy) {
   goog.asserts.assert(!this.parentBlock_, 'Block has parent.');
@@ -375,8 +379,8 @@ Blockly.BlockSvg.prototype.moveBy = function(dx, dy) {
 /**
  * Transforms a block by setting the translation on the transform attribute
  * of the block's SVG.
- * @param {number} x The x coordinate of the translation.
- * @param {number} y The y coordinate of the translation.
+ * @param {number} x The x coordinate of the translation in workspace units.
+ * @param {number} y The y coordinate of the translation in workspace units.
  */
 Blockly.BlockSvg.prototype.translate = function(x, y) {
   this.getSvgRoot().setAttribute('transform',
@@ -879,8 +883,10 @@ Blockly.BlockSvg.prototype.showContextMenu_ = function(e) {
 /**
  * Move the connections for this block and all blocks attached under it.
  * Also update any attached bubbles.
- * @param {number} dx Horizontal offset from current location.
- * @param {number} dy Vertical offset from current location.
+ * @param {number} dx Horizontal offset from current location, in workspace
+ *     units.
+ * @param {number} dy Vertical offset from current location, in workspace
+ *     units.
  * @private
  */
 Blockly.BlockSvg.prototype.moveConnections_ = function(dx, dy) {

core/rendered_connection.js

@@ -38,15 +38,22 @@ goog.require('Blockly.Connection');
  */
 Blockly.RenderedConnection = function(source, type) {
   Blockly.RenderedConnection.superClass_.constructor.call(this, source, type);
+
+  /**
+   * Workspace units, (0, 0) is top left of block.
+   * @type {!goog.math.Coordinate}
+   * @private
+   */
   this.offsetInBlock_ = new goog.math.Coordinate(0, 0);
 };
 goog.inherits(Blockly.RenderedConnection, Blockly.Connection);
 
 /**
- * Returns the distance between this connection and another connection.
+ * Returns the distance between this connection and another connection in
+ * workspace units.
  * @param {!Blockly.Connection} otherConnection The other connection to measure
  *     the distance to.
- * @return {number} The distance between connections.
+ * @return {number} The distance between connections, in workspace units.
  */
 Blockly.RenderedConnection.prototype.distanceFrom = function(otherConnection) {
   var xDiff = this.x_ - otherConnection.x_;
@@ -102,8 +109,8 @@ Blockly.RenderedConnection.prototype.bumpAwayFrom_ = function(staticConnection)
 
 /**
  * Change the connection's coordinates.
- * @param {number} x New absolute x coordinate.
- * @param {number} y New absolute y coordinate.
+ * @param {number} x New absolute x coordinate, in workspace coordinates.
+ * @param {number} y New absolute y coordinate, in workspace coordinates.
  */
 Blockly.RenderedConnection.prototype.moveTo = function(x, y) {
   // Remove it from its old location in the database (if already present)
@@ -120,8 +127,8 @@ Blockly.RenderedConnection.prototype.moveTo = function(x, y) {
 
 /**
  * Change the connection's coordinates.
- * @param {number} dx Change to x coordinate.
- * @param {number} dy Change to y coordinate.
+ * @param {number} dx Change to x coordinate, in workspace units.
+ * @param {number} dy Change to y coordinate, in workspace units.
  */
 Blockly.RenderedConnection.prototype.moveBy = function(dx, dy) {
   this.moveTo(this.x_ + dx, this.y_ + dy);
@@ -129,9 +136,9 @@ Blockly.RenderedConnection.prototype.moveBy = function(dx, dy) {
 
 /**
  * Move this connection to the location given by its offset within the block and
- * the coordinate of the block's top left corner.
- * @param {!goog.math.Coordinate} blockTL The coordinate of the top left corner
- *     of the block.
+ * the location of the block's top left corner.
+ * @param {!goog.math.Coordinate} blockTL The location of the top left corner
+ *     of the block, in workspace coordinates.
  */
 Blockly.RenderedConnection.prototype.moveToOffset = function(blockTL) {
   this.moveTo(blockTL.x + this.offsetInBlock_.x,
@@ -140,8 +147,8 @@ Blockly.RenderedConnection.prototype.moveToOffset = function(blockTL) {
 
 /**
  * Set the offset of this connection relative to the top left of its block.
- * @param {number} x The new relative x.
- * @param {number} y The new relative y.
+ * @param {number} x The new relative x, in workspace units.
+ * @param {number} y The new relative y, in workspace units.
  */
 Blockly.RenderedConnection.prototype.setOffsetInBlock = function(x, y) {
   this.offsetInBlock_.x = x;
@@ -170,6 +177,7 @@ Blockly.RenderedConnection.prototype.tighten_ = function() {
 
 /**
  * Find the closest compatible connection to this connection.
+ * All parameters are in workspace units
  * @param {number} maxLimit The maximum radius to another connection.
  * @param {number} dx Horizontal offset between this connection's location
  *     in the database and the current location (as a result of dragging).
@@ -294,7 +302,8 @@ Blockly.RenderedConnection.prototype.hideAll = function() {
 /**
  * Check if the two connections can be dragged to connect to each other.
  * @param {!Blockly.Connection} candidate A nearby connection to check.
- * @param {number} maxRadius The maximum radius allowed for connections.
+ * @param {number} maxRadius The maximum radius allowed for connections, in
+ *     workspace units.
  * @return {boolean} True if the connection is allowed, false otherwise.
  */
 Blockly.RenderedConnection.prototype.isConnectionAllowed = function(candidate,
@@ -353,7 +362,8 @@ Blockly.RenderedConnection.prototype.respawnShadow_ = function() {
 /**
  * Find all nearby compatible connections to this connection.
  * Type checking does not apply, since this function is used for bumping.
- * @param {number} maxLimit The maximum radius to another connection.
+ * @param {number} maxLimit The maximum radius to another connection, in
+ *     workspace units.
  * @return {!Array.<!Blockly.Connection>} List of connections.
  * @private
  */

core/touch.js

@@ -189,6 +189,20 @@ Blockly.Touch.shouldHandleEvent = function(e) {
       Blockly.Touch.checkTouchIdentifier(e);
 };
 
+/**
+ * Get the touch identifier from the given event.  If it was a mouse event, the
+ * identifier is the string 'mouse'.
+ * @param {!Event} e Mouse event or touch event.
+ * @return {string} The touch identifier from the first changed touch, if
+ *     defined.  Otherwise 'mouse'.
+ */
+Blockly.Touch.getTouchIdentifierFromEvent = function(e) {
+  return (e.changedTouches && e.changedTouches[0] &&
+      e.changedTouches[0].identifier != undefined &&
+      e.changedTouches[0].identifier != null) ?
+      e.changedTouches[0].identifier : 'mouse';
+};
+
 /**
  * Check whether the touch identifier on the event matches the current saved
  * identifier.  If there is no identifier, that means it's a mouse event and
@@ -202,10 +216,7 @@ Blockly.Touch.shouldHandleEvent = function(e) {
  *     saved identifier.
  */
 Blockly.Touch.checkTouchIdentifier = function(e) {
-  var identifier = (e.changedTouches && e.changedTouches[0] &&
-        e.changedTouches[0].identifier != undefined &&
-        e.changedTouches[0].identifier != null) ?
-        e.changedTouches[0].identifier : 'mouse';
+  var identifier = Blockly.Touch.getTouchIdentifierFromEvent(e);
 
   // if (Blockly.touchIdentifier_ )is insufficient because android touch
   // identifiers may be zero.