Clarify code and documentation

js/util/actor.js

@@ -23,14 +23,34 @@ function Actor(target, parent, mapId) {
     this.target.addEventListener('message', this.receive, false);
 }
 
+/**
+ * Sends a message from a main-thread map to a Worker or from a Worker back to
+ * a main-thread map instance.
+ *
+ * @param {string} type The name of the target method to invoke or '[source-type].name' for a method on a WorkerSource.
+ * @param {object} data
+ * @param {Function} [callback]
+ * @param {Array} [buffers] A list of buffers to "transfer" (see https://developer.mozilla.org/en-US/docs/Web/API/Transferable)
+ * @param {string} [targetMapId] A particular mapId to which to send this message.
+ * @private
+ */
+Actor.prototype.send = function(type, data, callback, buffers, targetMapId) {
+    var id = callback ? this.mapId + ':' + this.callbackID++ : null;
+    if (callback) this.callbacks[id] = callback;
+    this.postMessage({
+        targetMapId: targetMapId,
+        sourceMapId: this.mapId,
+        type: type,
+        id: String(id),
+        data: data
+    }, buffers);
+};
+
 Actor.prototype.receive = function(message) {
     var data = message.data,
         id = data.id,
         callback;
 
-    // if we're on the main thread handling a message from the worker, make
-    // sure that we only handle messages directed at this actor's the map
-    // instance
     if (data.targetMapId && this.mapId !== data.targetMapId)
         return;
 
@@ -40,19 +60,19 @@ Actor.prototype.receive = function(message) {
         if (callback) callback(data.error || null, data.data);
     } else if (typeof data.id !== 'undefined' && this.parent[data.type]) {
         // data.type == 'load tile', 'remove tile', etc.
-        this.parent[data.type](data.mapId, data.data, done.bind(this));
+        this.parent[data.type](data.sourceMapId, data.data, done.bind(this));
     } else if (typeof data.id !== 'undefined' && this.parent.getWorkerSource) {
         // data.type == sourcetype.method
         var keys = data.type.split('.');
-        var workerSource = this.parent.getWorkerSource(data.mapId, keys[0]);
+        var workerSource = this.parent.getWorkerSource(data.sourceMapId, keys[0]);
         workerSource[keys[1]](data.data, done.bind(this));
     } else {
         this.parent[data.type](data.data);
     }
 
     function done(err, data, buffers) {
         this.postMessage({
-            mapId: this.mapId,
+            sourceMapId: this.mapId,
             type: '<response>',
             id: String(id),
             error: err ? String(err) : null,
@@ -61,18 +81,6 @@ Actor.prototype.receive = function(message) {
     }
 };
 
-Actor.prototype.send = function(type, data, callback, buffers, targetMapId) {
-    var id = callback ? this.mapId + ':' + this.callbackID++ : null;
-    if (callback) this.callbacks[id] = callback;
-    this.postMessage({
-        targetMapId: targetMapId,
-        mapId: this.mapId,
-        type: type,
-        id: String(id),
-        data: data
-    }, buffers);
-};
-
 Actor.prototype.remove = function () {
     this.target.removeEventListener('message', this.receive, false);
 };