providers documentation

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;
+