providers documentation

6 files changed, 108 insertions, 11 deletions

diff --git a/lib/autoprovider.js b/lib/autoprovider.js
index 8460a144f..a2c265ccb 100644
--- a/lib/autoprovider.js
+++ b/lib/autoprovider.js
@@ -33,13 +33,16 @@ 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
+/**
+ * AutoProvider object prototype is implementing 'provider protocol'
+ * Automatically tries to setup correct provider(Qt, WebSockets or HttpRpc)
+ * 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;
diff --git a/lib/contract.js b/lib/contract.js
index eb7fbf018..d38746f01 100644
--- a/lib/contract.js
+++ b/lib/contract.js
@@ -27,9 +27,29 @@ if (process.env.NODE_ENV !== 'build') {
 
 var abi = require('./abi');
 
-// method signature length in bytes
+/// method signature length in bytes
 var ETH_METHOD_SIGNATURE_LENGTH = 4;
 
+/**
+ * This method should be called when we want to call / transact some solidity method from javascript
+ * it returns an object which has same methods available as solidity contract description
+ * usage example: 
+ *
+ * var abi = [{
+ *      name: 'myMethod',
+ *      inputs: [{ name: 'a', type: 'string' }],
+ *      outputs: [{name 'd', type: 'string' }]
+ * }];  // contract abi
+ *
+ * var myContract = web3.eth.contract('0x0123123121', abi); // creation of contract object
+ *
+ * myContract.myMethod('this is test string param for call').cal(); // myMethod call
+ * myContract.myMethod('this is test string param for transact').transact() // myMethod transact
+ *
+ * @param address - address of the contract, which should be called
+ * @param desc - abi json description of the contract, which is being created
+ * @returns contract object
+ */
 var contract = function (address, desc) {
     var inputParser = abi.inputParser(desc);
     var outputParser = abi.outputParser(desc);
@@ -70,3 +90,4 @@ var contract = function (address, desc) {
 };
 
 module.exports = contract;
+
diff --git a/lib/httprpc.js b/lib/httprpc.js
index d315201f1..de3ae8478 100644
--- a/lib/httprpc.js
+++ b/lib/httprpc.js
@@ -26,11 +26,21 @@ if (process.env.NODE_ENV !== 'build') {
     var XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest; // jshint ignore:line
 }
 
+/**
+ * HttpRpcProvider object prototype is implementing 'provider protocol'
+ * Should be used when we want to connect to ethereum backend over http && jsonrpc
+ * It's compatible with cpp client
+ * The contructor allows to specify host uri
+ * This provider is using in-browser polling mechanism
+ */
 var HttpRpcProvider = function (host) {
     this.handlers = [];
     this.host = host;
 };
 
+/// Transforms inner message to proper jsonrpc object
+/// @param inner message object
+/// @returns jsonrpc object
 function formatJsonRpcObject(object) {
     return {
         jsonrpc: '2.0',
@@ -40,6 +50,9 @@ function formatJsonRpcObject(object) {
     };
 }
 
+/// Transforms jsonrpc object to inner message
+/// @param incoming jsonrpc message 
+/// @returns inner message object
 function formatJsonRpcMessage(message) {
     var object = JSON.parse(message);
 
@@ -50,6 +63,10 @@ function formatJsonRpcMessage(message) {
     };
 }
 
+/// Prototype object method 
+/// Asynchronously sends request to server
+/// @param payload is inner message object
+/// @param cb is callback which is being called when response is comes back
 HttpRpcProvider.prototype.sendRequest = function (payload, cb) {
     var data = formatJsonRpcObject(payload);
 
@@ -63,6 +80,11 @@ HttpRpcProvider.prototype.sendRequest = function (payload, cb) {
     };
 };
 
+/// Prototype object method
+/// Should be called when we want to send single api request to server
+/// Asynchronous
+/// On response it passes message to handlers
+/// @param payload is inner message object
 HttpRpcProvider.prototype.send = function (payload) {
     var self = this;
     this.sendRequest(payload, function (request) {
@@ -72,6 +94,13 @@ HttpRpcProvider.prototype.send = function (payload) {
     });
 };
 
+/// Prototype object method
+/// Should be called only for polling requests
+/// Asynchronous
+/// On response it passege message to handlers, but only if message's result is true or not empty array
+/// Otherwise response is being silently ignored
+/// @param payload is inner message object
+/// @id is id of poll that we are calling
 HttpRpcProvider.prototype.poll = function (payload, id) {
     var self = this;
     this.sendRequest(payload, function (request) {
@@ -85,6 +114,8 @@ HttpRpcProvider.prototype.poll = function (payload, id) {
     });
 };
 
+/// Prototype object property
+/// Should be used to set message handlers for this provider
 Object.defineProperty(HttpRpcProvider.prototype, "onmessage", {
     set: function (handler) {
         this.handlers.push(handler);
@@ -92,3 +123,4 @@ Object.defineProperty(HttpRpcProvider.prototype, "onmessage", {
 });
 
 module.exports = HttpRpcProvider;
+
diff --git a/lib/providermanager.js b/lib/providermanager.js
index 28122cb42..00266154d 100644
--- a/lib/providermanager.js
+++ b/lib/providermanager.js
@@ -28,7 +28,15 @@ if (process.env.NODE_ENV !== 'build') {
     var web3 = require('./web3'); // jshint ignore:line
 }
 
-/// Provider manager object prototype
+/**
+ * Provider manager object prototype
+ * It's responsible for passing messages to providers
+ * If no provider is set it's responsible for queuing requests
+ * It's also responsible for polling the ethereum node for incoming messages
+ * Default poll timeout is 12 seconds
+ * If we are running ethereum.js inside ethereum browser, there are backend based tools responsible for polling,
+ * and provider manager polling mechanism is not used
+ */
 var ProviderManager = function() {
     this.queued = [];
     this.polls = [];
@@ -111,3 +119,4 @@ ProviderManager.prototype.stopPolling = function (pollId) {
 };
 
 module.exports = ProviderManager;
+
diff --git a/lib/qt.js b/lib/qt.js
index f02239547..1b3a9547b 100644
--- a/lib/qt.js
+++ b/lib/qt.js
@@ -21,6 +21,11 @@
  * @date 2014
  */
 
+/**
+ * QtProvider object prototype is implementing 'provider protocol'
+ * Should be used inside ethereum browser. It's compatible with cpp and go clients.
+ * It uses navigator.qt object to pass the messages to native bindings
+ */
 var QtProvider = function() {
     this.handlers = [];
 
@@ -32,10 +37,17 @@ var QtProvider = function() {
     };
 };
 
+/// Prototype object method
+/// Should be called when we want to send single api request to native bindings
+/// Asynchronous
+/// Response will be received by navigator.qt.onmessage method and passed to handlers
+/// @param payload is inner message object
 QtProvider.prototype.send = function(payload) {
     navigator.qt.postMessage(JSON.stringify(payload));
 };
 
+/// Prototype object property
+/// Should be used to set message handlers for this provider
 Object.defineProperty(QtProvider.prototype, "onmessage", {
     set: function(handler) {
         this.handlers.push(handler);
diff --git a/lib/websocket.js b/lib/websocket.js
index 5b40075e4..e8663ecf5 100644
--- a/lib/websocket.js
+++ b/lib/websocket.js
@@ -27,9 +27,17 @@ if (process.env.NODE_ENV !== 'build') {
     var WebSocket = require('ws'); // jshint ignore:line
 }
 
+/**
+ * WebSocketProvider object prototype is implementing 'provider protocol'
+ * Should be used when we want to connect to ethereum backend over websockets
+ * It's compatible with go client
+ * The constructor allows to specify host uri
+ */
 var WebSocketProvider = function(host) {
+
     // onmessage handlers
     this.handlers = [];
+
     // queue will be filled with messages if send is invoked before the ws is ready
     this.queued = [];
     this.ready = false;
@@ -46,15 +54,20 @@ var WebSocketProvider = function(host) {
     this.ws.onopen = function() {
         self.ready = true;
 
-        for(var i = 0; i < self.queued.length; i++) {
+        for (var i = 0; i < self.queued.length; i++) {
             // Resend
             self.send(self.queued[i]);
         }
     };
 };
 
+/// Prototype object method
+/// Should be called when we want to send single api request to server
+/// Asynchronous, it's using websockets
+/// Response for the call will be received by ws.onmessage
+/// @param payload is inner message object
 WebSocketProvider.prototype.send = function(payload) {
-    if(this.ready) {
+    if (this.ready) {
         var data = JSON.stringify(payload);
 
         this.ws.send(data);
@@ -63,13 +76,20 @@ WebSocketProvider.prototype.send = function(payload) {
     }
 };
 
+/// Prototype object method
+/// Should be called to add handlers
 WebSocketProvider.prototype.onMessage = function(handler) {
     this.handlers.push(handler);
 };
 
+/// Prototype object method
+/// Should be called to close websockets connection
 WebSocketProvider.prototype.unload = function() {
     this.ws.close();
 };
+
+/// Prototype object property
+/// Should be used to set message handlers for this provider
 Object.defineProperty(WebSocketProvider.prototype, "onmessage", {
     set: function(provider) { this.onMessage(provider); }
 });