Merge commit '1a6dbeff6e86d65cae6d7db366cbaa4182eaff7f' into ethereumjs

Conflicts:
	libjsqrc/ethereumjs/dist/ethereum.js
	libjsqrc/ethereumjs/dist/ethereum.js.map
	libjsqrc/ethereumjs/dist/ethereum.min.js
	libjsqrc/ethereumjs/lib/abi.js

1 files changed, 43 insertions, 137 deletions

diff --git a/lib/web3.js b/lib/web3.js
index 4220114f9..25c2901a8 100644
--- a/lib/web3.js
+++ b/lib/web3.js
@@ -14,7 +14,7 @@
     You should have received a copy of the GNU Lesser General Public License
     along with ethereum.js.  If not, see <http://www.gnu.org/licenses/>.
 */
-/** @file main.js
+/** @file web3.js
  * @authors:
  *   Jeffrey Wilcke <jeff@ethdev.com>
  *   Marek Kotewicz <marek@ethdev.com>
@@ -23,6 +23,12 @@
  * @date 2014
  */
 
+var Filter = require('./filter');
+var ProviderManager = require('./providermanager');
+
+/// Recursively resolves all promises in given object and replaces the resolved values with promises
+/// @param any object/array/promise/anything else..
+/// @returns (resolves) object with replaced promises with their result 
 function flattenPromise (obj) {
     if (obj instanceof Promise) {
         return Promise.resolve(obj);
@@ -62,12 +68,14 @@ function flattenPromise (obj) {
     return Promise.resolve(obj);
 }
 
+/// @returns an array of objects describing web3 api methods
 var web3Methods = function () {
     return [
     { name: 'sha3', call: 'web3_sha3' }
     ];
 };
 
+/// @returns an array of objects describing web3.eth api methods
 var ethMethods = function () {
     var blockCall = function (args) {
         return typeof args[0] === "string" ? "eth_blockByHash" : "eth_blockByNumber";
@@ -101,6 +109,7 @@ var ethMethods = function () {
     return methods;
 };
 
+/// @returns an array of objects describing web3.eth api properties
 var ethProperties = function () {
     return [
     { name: 'coinbase', getter: 'eth_coinbase', setter: 'eth_setCoinbase' },
@@ -115,6 +124,7 @@ var ethProperties = function () {
     ];
 };
 
+/// @returns an array of objects describing web3.db api methods
 var dbMethods = function () {
     return [
     { name: 'put', call: 'db_put' },
@@ -124,6 +134,7 @@ var dbMethods = function () {
     ];
 };
 
+/// @returns an array of objects describing web3.shh api methods
 var shhMethods = function () {
     return [
     { name: 'post', call: 'shh_post' },
@@ -134,6 +145,7 @@ var shhMethods = function () {
     ];
 };
 
+/// @returns an array of objects describing web3.eth.watch api methods
 var ethWatchMethods = function () {
     var newFilter = function (args) {
         return typeof args[0] === 'string' ? 'eth_newFilterString' : 'eth_newFilter';
@@ -146,6 +158,7 @@ var ethWatchMethods = function () {
     ];
 };
 
+/// @returns an array of objects describing web3.shh.watch api methods
 var shhWatchMethods = function () {
     return [
     { name: 'newFilter', call: 'shh_newFilter' },
@@ -154,6 +167,8 @@ var shhWatchMethods = function () {
     ];
 };
 
+/// creates methods in a given object based on method description on input
+/// setups api calls for these methods
 var setupMethods = function (obj, methods) {
     methods.forEach(function (method) {
         obj[method.name] = function () {
@@ -177,6 +192,8 @@ var setupMethods = function (obj, methods) {
     });
 };
 
+/// creates properties in a given object based on properties description on input
+/// setups api calls for these properties
 var setupProperties = function (obj, properties) {
     properties.forEach(function (property) {
         var proto = {};
@@ -221,7 +238,7 @@ var decToHex = function (dec) {
     return parseInt(dec).toString(16);
 };
 
-
+/// setups web3 object, and it's in-browser executed methods
 var web3 = {
     _callbacks: {},
     _events: {},
@@ -237,6 +254,7 @@ var web3 = {
         return hex;
     },
 
+    /// @returns ascii string representation of hex value prefixed with 0x
     toAscii: function(hex) {
         // Find termination
         var str = "";
@@ -244,17 +262,18 @@ var web3 = {
         if (hex.substring(0, 2) === '0x')
             i = 2;
         for(; i < l; i+=2) {
-            var code = hex.charCodeAt(i);
+            var code = parseInt(hex.substr(i, 2), 16);
             if(code === 0) {
                 break;
             }
 
-            str += String.fromCharCode(parseInt(hex.substr(i, 2), 16));
+            str += String.fromCharCode(code);
         }
 
         return str;
     },
 
+    /// @returns hex representation (prefixed by 0x) of ascii string
     fromAscii: function(str, pad) {
         pad = pad === undefined ? 0 : pad;
         var hex = this.toHex(str);
@@ -263,14 +282,17 @@ var web3 = {
         return "0x" + hex;
     },
 
+    /// @returns decimal representaton of hex value prefixed by 0x
     toDecimal: function (val) {
         return hexToDec(val.substring(2));
     },
 
+    /// @returns hex representation (prefixed by 0x) of decimal value
     fromDecimal: function (val) {
         return "0x" + decToHex(val);
     },
 
+    /// used to transform value/string to eth string
     toEth: function(str) {
         var val = typeof str === "string" ? str.indexOf('0x') === 0 ? parseInt(str.substr(2), 16) : parseInt(str) : str;
         var unit = 0;
@@ -294,24 +316,24 @@ var web3 = {
         return s + ' ' + units[unit];
     },
 
+    /// eth object prototype
     eth: {
-        prototype: Object(), // jshint ignore:line
         watch: function (params) {
             return new Filter(params, ethWatch);
         }
     },
 
-    db: {
-        prototype: Object() // jshint ignore:line
-    },
+    /// db object prototype
+    db: {},
 
+    /// shh object prototype
     shh: {
-        prototype: Object(), // jshint ignore:line
         watch: function (params) {
             return new Filter(params, shhWatch);
         }
     },
 
+    /// used by filter to register callback with given id
     on: function(event, id, cb) {
         if(web3._events[event] === undefined) {
             web3._events[event] = {};
@@ -321,6 +343,7 @@ var web3 = {
         return this;
     },
 
+    /// used by filter to unregister callback with given id
     off: function(event, id) {
         if(web3._events[event] !== undefined) {
             delete web3._events[event][id];
@@ -329,6 +352,7 @@ var web3 = {
         return this;
     },
 
+    /// used to trigger callback registered by filter
     trigger: function(event, id, data) {
         var callbacks = web3._events[event];
         if (!callbacks || !callbacks[id]) {
@@ -336,9 +360,15 @@ var web3 = {
         }
         var cb = callbacks[id];
         cb(data);
+    },
+
+    /// @returns true if provider is installed
+    haveProvider: function() {
+        return !!web3.provider.provider;
     }
 };
 
+/// setups all api methods
 setupMethods(web3, web3Methods());
 setupMethods(web3.eth, ethMethods());
 setupProperties(web3.eth, ethProperties());
@@ -348,85 +378,14 @@ setupMethods(web3.shh, shhMethods());
 var ethWatch = {
     changed: 'eth_changed'
 };
+
 setupMethods(ethWatch, ethWatchMethods());
+
 var shhWatch = {
     changed: 'shh_changed'
 };
-setupMethods(shhWatch, shhWatchMethods());
-
-var ProviderManager = function() {
-    this.queued = [];
-    this.polls = [];
-    this.ready = false;
-    this.provider = undefined;
-    this.id = 1;
-
-    var self = this;
-    var poll = function () {
-        if (self.provider && self.provider.poll) {
-            self.polls.forEach(function (data) {
-                data.data._id = self.id;
-                self.id++;
-                self.provider.poll(data.data, data.id);
-            });
-        }
-        setTimeout(poll, 12000);
-    };
-    poll();
-};
-
-ProviderManager.prototype.send = function(data, cb) {
-    data._id = this.id;
-    if (cb) {
-        web3._callbacks[data._id] = cb;
-    }
-
-    data.args = data.args || [];
-    this.id++;
-
-    if(this.provider !== undefined) {
-        this.provider.send(data);
-    } else {
-        console.warn("provider is not set");
-        this.queued.push(data);
-    }
-};
-
-ProviderManager.prototype.set = function(provider) {
-    if(this.provider !== undefined && this.provider.unload !== undefined) {
-        this.provider.unload();
-    }
-
-    this.provider = provider;
-    this.ready = true;
-};
-
-ProviderManager.prototype.sendQueued = function() {
-    for(var i = 0; this.queued.length; i++) {
-        // Resend
-        this.send(this.queued[i]);
-    }
-};
-
-ProviderManager.prototype.installed = function() {
-    return this.provider !== undefined;
-};
-
-ProviderManager.prototype.startPolling = function (data, pollId) {
-    if (!this.provider || !this.provider.poll) {
-        return;
-    }
-    this.polls.push({data: data, id: pollId});
-};
 
-ProviderManager.prototype.stopPolling = function (pollId) {
-    for (var i = this.polls.length; i--;) {
-        var poll = this.polls[i];
-        if (poll.id === pollId) {
-            this.polls.splice(i, 1);
-        }
-    }
-};
+setupMethods(shhWatch, shhWatchMethods());
 
 web3.provider = new ProviderManager();
 
@@ -436,60 +395,7 @@ web3.setProvider = function(provider) {
     web3.provider.sendQueued();
 };
 
-web3.haveProvider = function() {
-    return !!web3.provider.provider;
-};
-
-var Filter = function(options, impl) {
-    this.impl = impl;
-    this.callbacks = [];
-
-    var self = this;
-    this.promise = impl.newFilter(options);
-    this.promise.then(function (id) {
-        self.id = id;
-        web3.on(impl.changed, id, self.trigger.bind(self));
-        web3.provider.startPolling({call: impl.changed, args: [id]}, id);
-    });
-};
-
-Filter.prototype.arrived = function(callback) {
-    this.changed(callback);
-};
-
-Filter.prototype.changed = function(callback) {
-    var self = this;
-    this.promise.then(function(id) {
-        self.callbacks.push(callback);
-    });
-};
-
-Filter.prototype.trigger = function(messages) {
-    for(var i = 0; i < this.callbacks.length; i++) {
-        this.callbacks[i].call(this, messages);
-    }
-};
-
-Filter.prototype.uninstall = function() {
-    var self = this;
-    this.promise.then(function (id) {
-        self.impl.uninstallFilter(id);
-        web3.provider.stopPolling(id);
-        web3.off(impl.changed, id);
-    });
-};
-
-Filter.prototype.messages = function() {
-    var self = this;
-    return this.promise.then(function (id) {
-        return self.impl.getMessages(id);
-    });
-};
-
-Filter.prototype.logs = function () {
-    return this.messages();
-};
-
+/// callled when there is new incoming message
 function messageHandler(data) {
     if(data._event !== undefined) {
         web3.trigger(data._event, data._id, data.data);