From 8d1f96cc0aa608c319a48af5a3c2397b694d5930 Mon Sep 17 00:00:00 2001
From: Marek Kotewicz <marek.kotewicz@gmail.com>
Date: Wed, 14 Jan 2015 10:50:34 +0100
Subject: [PATCH] few comments

---
 lib/autoprovider.js | 10 ++++++++++
 lib/web3.js         | 30 +++++++++++++++++-------------
 2 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/lib/autoprovider.js b/lib/autoprovider.js
index 113873674..8460a144f 100644
--- a/lib/autoprovider.js
+++ b/lib/autoprovider.js
@@ -33,6 +33,13 @@ if (process.env.NODE_ENV !== 'build') {
     var web3 = require('./web3'); // jshint ignore:line
 }
 
+/// Automatically tries to setup correct provider
+/// First it checkes if we are ethereum browser (if navigator.qt object is available)
+/// if yes, we are using QtProvider
+/// if no, we check if it is possible to establish websockets connection with ethereum (ws://localhost:40404/eth is default)
+/// if it's not possible, we are using httprpc provider (http://localhost:8080)
+/// The constructor allows you to specify uris on which we are trying to connect over http or websockets
+/// You can do that by passing objects with fields httrpc and websockets
 var AutoProvider = function (userOptions) {
     if (web3.haveProvider()) {
         return;
@@ -81,6 +88,8 @@ var AutoProvider = function (userOptions) {
     };
 };
 
+/// Sends message forward to the provider, that is being used
+/// if provider is not yet set, enqueues the message
 AutoProvider.prototype.send = function (payload) {
     if (this.provider) {
         this.provider.send(payload);
@@ -89,6 +98,7 @@ AutoProvider.prototype.send = function (payload) {
     this.sendQueue.push(payload);
 };
 
+/// On incoming message sends the message to the provider that is currently being used
 Object.defineProperty(AutoProvider.prototype, 'onmessage', {
     set: function (handler) {
         if (this.provider) {
diff --git a/lib/web3.js b/lib/web3.js
index 47decb8bd..25c2901a8 100644
--- a/lib/web3.js
+++ b/lib/web3.js
@@ -254,6 +254,7 @@ var web3 = {
         return hex;
     },
 
+    /// @returns ascii string representation of hex value prefixed with 0x
     toAscii: function(hex) {
         // Find termination
         var str = "";
@@ -272,6 +273,7 @@ var web3 = {
         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);
@@ -280,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;
@@ -311,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] = {};
@@ -338,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];
@@ -346,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]) {
@@ -353,6 +360,11 @@ var web3 = {
         }
         var cb = callbacks[id];
         cb(data);
+    },
+
+    /// @returns true if provider is installed
+    haveProvider: function() {
+        return !!web3.provider.provider;
     }
 };
 
@@ -375,7 +387,6 @@ var shhWatch = {
 
 setupMethods(shhWatch, shhWatchMethods());
 
-
 web3.provider = new ProviderManager();
 
 web3.setProvider = function(provider) {
@@ -384,13 +395,6 @@ web3.setProvider = function(provider) {
     web3.provider.sendQueued();
 };
 
-/// returns true if provider is installed
-web3.haveProvider = function() {
-    return !!web3.provider.provider;
-};
-
-
-
 /// callled when there is new incoming message
 function messageHandler(data) {
     if(data._event !== undefined) {