Add jsdocs and documentation to UnspenOutput and Insight

docs/guide/block.md

@@ -8,7 +8,6 @@ description: A simple interface to parse and validate a bitcoin blocks.
 A Block instance represents the information of a block in the bitcoin network. Given a hexadecimal string representation of the serialization of a block with its transactions, you can instantiate a Block instance. Methods are provided to calculate and check the merkle root hash (if enough data is provided), but transactions won't necessarily be valid spends, and this class won't validate them. A binary representation as a `Buffer` instance is also valid input for a Block's constructor. 
 
 ```javascript
-
 // instantiate a new block instance
 var block = new Block(hexaEncodedBlock);
 
@@ -30,7 +29,6 @@ For detailed technical information about a block please visit [Blocks](https://e
 Each instance of Block has a BlockHeader *(which can be instantiated separately)*. The header has validation methods, to verify that the block.
 
 ```javascript
-
 // will verify that the nonce demonstrates enough proof of work
 assert(block.header.validProofOfWork());
 

docs/guide/index.md

@@ -30,6 +30,9 @@ To get started, just `npm install bitcore` or `bower install bitcore`.
 * [Managing a pool of peers](pool.md)
 * [Connecting to a bitcoind instance through JSON-RPC](jsonrpc.md)
 
+## Blockchain Explorers
+* [Insight](insight.md)
+
 ## Extra
 * [Crypto](crypto.md)
 * [Encoding](encoding.md)

docs/guide/insight.md

@@ -0,0 +1,34 @@
+title: Insight Explorer
+description: Allows users to fetch information about the state of the blockchain from a trusted Insight server.
+---
+# Insight
+
+## Description
+
+`bitcore.explorers.Insight` is a simple agent to perform queries to the blockchain. There are currently two methods (the API will grow as features are requested): `getUnspentUtxos` and `broadcast`.
+
+### Retrieving Unspent UTXOs for an Address (or set of)
+
+```javascript
+var insight = new Insight();
+insight.getUnspentUtxos('1Bitcoin...', function(err, utxos) {
+  if (err) {
+    // Handle errors...
+  } else {
+    // Maybe use the UTXOs to create a transaction
+  }
+});
+```
+
+### Broadcasting a Transaction
+
+```javascript
+var insight = new Insight();
+insight.broadcast(tx, function(err, returnedTxId) {
+  if (err) {
+    // Handle errors...
+  } else {
+    // Mark the transaction as broadcasted
+  }
+});
+```

docs/guide/unspentoutput.md

@@ -0,0 +1,39 @@
+title: UnspentOutput
+description: A stateless model to represent an unspent output and associated information.
+---
+# UnspentOutput
+
+## Description
+
+`bitcore.Transaction.UnspentOutput` is a class with stateless instances that provides information about an unspent output:
+- Transaction ID and output index
+- The "scriptPubKey", the script included in the output
+- Amount of satoshis associated
+- Address, if available
+
+## Parameters
+
+The constructor is quite permissive with the input arguments. It can take outputs straight out of bitcoind's getunspent RPC call. Some of the names are not very informative for new users, so the UnspentOutput constructor also understands these aliases:
+- `scriptPubKey`: just `script` is also accepted
+- `amount`: expected value is in BTC, but also `satoshis` is accepted
+- `vout`: this is the index of the output in the transaction, renamed to `outputIndex`
+- `txid`: `txId`
+
+## Example
+
+```javascript
+var utxo = new UnspentOutput({
+  "txid" : "a0a08e397203df68392ee95b3f08b0b3b3e2401410a38d46ae0874f74846f2e9",
+  "vout" : 0,
+  "address" : "mgJT8iegL4f9NCgQFeFyfvnSw1Yj4M5Woi",
+  "scriptPubKey" : "76a914089acaba6af8b2b4fb4bed3b747ab1e4e60b496588ac",
+  "amount" : 0.00070000
+});
+var utxo = new UnspentOutput({
+  "txId" : "a0a08e397203df68392ee95b3f08b0b3b3e2401410a38d46ae0874f74846f2e9",
+  "outputIndex" : 0,
+  "address" : "mgJT8iegL4f9NCgQFeFyfvnSw1Yj4M5Woi",
+  "script" : "76a914089acaba6af8b2b4fb4bed3b747ab1e4e60b496588ac",
+  "satoshis" : 70000
+});
+```

lib/explorers/insight.js

@@ -10,8 +10,13 @@ var UnspentOutput = Transaction.UnspentOutput;
 
 var request = require('request');
 
-// var insight = new Insight(Networks.livenet);
+/**
-
+ * Allows the retrieval of information regarding the state of the blockchain
+ * (and broadcasting of transactions) from/to a trusted Insight server.
+ * @param {string=} url the url of the Insight server
+ * @param {Network=} network whether to use livenet or testnet
+ * @constructor
+ */
 function Insight(url, network) {
   if (!url && !network) {
     return new Insight(Networks.defaultNetwork);
@@ -31,6 +36,17 @@ function Insight(url, network) {
   return this;
 }
 
+/**
+ * @callback Insight.GetUnspentUtxosCallback
+ * @param {Error} err
+ * @param {Array.UnspentOutput} utxos
+ */
+
+/**
+ * Retrieve a list of unspent outputs associated with an address or set of addresses
+ * @param {Address|string|Array.Address|Array.string} addresses
+ * @param {GetUnspentUtxosCallback} callback
+ */
 Insight.prototype.getUnspentUtxos = function(addresses, callback) {
   $.checkArgument(_.isFunction(callback));
   if (!_.isArray(addresses)) {
@@ -50,6 +66,17 @@ Insight.prototype.getUnspentUtxos = function(addresses, callback) {
   });
 };
 
+/**
+ * @callback Insight.BroadcastCallback
+ * @param {Error} err
+ * @param {string} txid
+ */
+
+/**
+ * Broadcast a transaction to the bitcoin network
+ * @param {transaction|string} transaction
+ * @param {BroadcastCallback} callback
+ */
 Insight.prototype.broadcast = function(transaction, callback) {
   $.checkArgument(JSUtil.isHexa(transaction) || transaction instanceof Transaction);
   $.checkArgument(_.isFunction(callback));
@@ -67,6 +94,13 @@ Insight.prototype.broadcast = function(transaction, callback) {
   });
 };
 
+/**
+ * Internal function to make a post request to the server
+ * @param {string} path
+ * @param {?} data
+ * @param {function} callback
+ * @private
+ */
 Insight.prototype.requestPost = function(path, data, callback) {
   $.checkArgument(_.isString(path));
   $.checkArgument(_.isFunction(callback));

lib/transaction/unspentoutput.js

@@ -8,6 +8,22 @@ var Script = require('../script');
 var Address = require('../address');
 var Unit = require('../unit');
 
+/**
+ * Represents an unspent output information: its script, associated amount and address,
+ * transaction id and output index.
+ *
+ * @constructor
+ * @param {object} data
+ * @param {string} data.txid the previous transaction id
+ * @param {string=} data.txId alias for `txid`
+ * @param {number} data.vout the index in the transaction
+ * @param {number=} data.outputIndex alias for `vout`
+ * @param {string|Script} data.scriptPubKey the script that must be resolved to release the funds
+ * @param {string|Script=} data.script alias for `scriptPubKey`
+ * @param {number} data.amount amount of bitcoins associated
+ * @param {number=} data.satoshis alias for `amount`, but expressed in satoshis (1 BTC = 1e8 satoshis)
+ * @param {string|Address=} data.address the associated address to the script, if provided
+ */
 function UnspentOutput(data) {
   /* jshint maxcomplexity: 20 */
   /* jshint maxstatements: 20 */
@@ -39,15 +55,28 @@ function UnspentOutput(data) {
   });
 }
 
+/**
+ * Provide an informative output when displaying this object in the console
+ * @returns string
+ */
 UnspentOutput.prototype.inspect = function() {
   return '<UnspentOutput: ' + this.txId + ':' + this.outputIndex +
          ', satoshis: ' + this.satoshis + ', address: ' + this.address + '>';
 };
 
+/**
+ * String representation: just "txid:index"
+ * @returns string
+ */
 UnspentOutput.prototype.toString = function() {
   return this.txId + ':' + this.outputIndex;
 };
 
+/**
+ * Deserialize an UnspentOutput from an object or JSON string
+ * @param {object|string} data
+ * @return UnspentOutput
+ */
 UnspentOutput.fromJSON = UnspentOutput.fromObject = function(data) {
   if (JSUtil.isValidJSON(data)) {
     data = JSON.parse(data);
@@ -55,10 +84,18 @@ UnspentOutput.fromJSON = UnspentOutput.fromObject = function(data) {
   return new UnspentOutput(data);
 };
 
+/**
+ * Retrieve a string representation of this object
+ * @return {string}
+ */
 UnspentOutput.prototype.toJSON = function() {
   return JSON.stringify(this.toObject());
 };
 
+/**
+ * Returns a plain object (no prototype or methods) with the associated infor for this output
+ * @return {object}
+ */
 UnspentOutput.prototype.toObject = function() {
   return {
     address: this.address.toString(),