Merge pull request #814 from braydonf/feature/jsdocs-to-markdown

Docs: Markdown API Reference

docs/config.json

@@ -1,6 +0,0 @@
-{
-    "useSideMenu": true,
-    "lineBreaks": "gfm",
-    "additionalFooterText": "Bitcore™ © 2013-2014 BitPay, Inc. Bitcore is released under the MIT license. ",
-    "anchorCharacter": "#"
-}

gulpfile.js

@@ -37,7 +37,10 @@ var jshint = require('gulp-jshint');
 var mocha = require('gulp-mocha');
 var runSequence = require('run-sequence');
 var shell = require('gulp-shell');
-
+var through = require('through2');
+var gutil = require('gulp-util');
+var jsdoc2md = require('jsdoc-to-markdown');
+var mfs = require('more-fs');
 
 var files = ['lib/**/*.js'];
 var tests = ['test/**/*.js'];
@@ -126,7 +129,32 @@ gulp.task('lint', function() {
 
 gulp.task('plato', shell.task(['plato -d report -r -l .jshintrc -t bitcore lib']));
 
-gulp.task('jsdoc', shell.task(['jsdoc -c .jsdoc.conf lib']));
+gulp.task('jsdoc', function() {
+
+  function jsdoc() {
+    return through.obj(function(file, enc, cb) {
+      
+      if (file.isNull()){
+        cb(null, file);
+        return;
+      }
+      if (file.isStream()) {
+        cb(new gutil.PluginError('gulp-jsdoc2md', 'Streaming not supported'));
+        return;
+      }
+      var destination = 'docs/api/'+file.path.replace(file.base, '').replace(/\.js$/, '.md');
+      jsdoc2md.render(file.path, {})
+        .on('error', function(err) {
+          gutil.log(gutil.colors.red('jsdoc2md failed', err.message));
+        })
+        .pipe(mfs.writeStream(destination));
+      cb(null, file);
+    });
+  }
+  
+  return gulp.src(files).pipe(jsdoc());
+
+});
 
 gulp.task('coverage', shell.task(['node_modules/.bin/./istanbul cover node_modules/.bin/_mocha -- --recursive']));
 

lib/address.js

@@ -19,6 +19,7 @@ var JSUtil = require('./util/js');
  * or `Address.PayToScriptHash` (the string `'scripthash'`). The network is an instance of {@link Network}.
  *
  * @example
+ * ```javascript
  * // validate that an input field is valid
  * var error = Address.getValidationError(input, 'testnet');
  * if (!error) {
@@ -30,6 +31,7 @@ var JSUtil = require('./util/js');
  *
  * // get an address from a public key
  * var address = Address(publicKey, 'testnet').toString();
+ * ```
  *
  * @param {*} data - The encoded data in various formats
  * @param {Network|String|number} [network] - The network: 'livenet' or 'testnet'
@@ -358,9 +360,11 @@ Address.fromJSON = function fromJSON(json) {
  * Will return a validation error if exists
  *
  * @example
+ * ```javascript
  *
  * var error = Address.getValidationError('15vkcKf7gB23wLAnZLmbVuMiiVDc1Nm4a2', 'testnet');
  * // a network mismatch error
+ * ```
  *
  * @param {String} data - The encoded data
  * @param {String} network - The network: 'livenet' or 'testnet'
@@ -381,9 +385,11 @@ Address.getValidationError = function(data, network, type) {
  * Will return a boolean if an address is valid
  *
  * @example
+ * ```javascript
  *
  * var valid = Address.isValid('15vkcKf7gB23wLAnZLmbVuMiiVDc1Nm4a2', 'livenet');
  * // true
+ * ```
  *
  * @param {String} data - The encoded data
  * @param {String} network - The network: 'livenet' or 'testnet'

lib/hdprivatekey.js

@@ -75,10 +75,12 @@ function HDPrivateKey(arg) {
  * derived. See the example usage for clarification.
  *
  * @example
+ * ```javascript
  * var parent = new HDPrivateKey('xprv...');
  * var child_0_1_2h = parent.derive(0).derive(1).derive(2, true);
  * var copy_of_child_0_1_2h = parent.derive("m/0/1/2'");
  * assert(child_0_1_2h.xprivkey === copy_of_child_0_1_2h);
+ * ```
  *
  * @param {string|number} arg
  * @param {boolean?} hardened

lib/hdpublickey.js

@@ -78,10 +78,12 @@ function HDPublicKey(arg) {
  * derived. See the example usage for clarification.
  *
  * @example
+ * ```javascript
  * var parent = new HDPublicKey('xpub...');
  * var child_0_1_2 = parent.derive(0).derive(1).derive(2);
  * var copy_of_child_0_1_2 = parent.derive("m/0/1/2");
  * assert(child_0_1_2.xprivkey === copy_of_child_0_1_2);
+ * ```
  *
  * @param {string|number} arg
  * @param {boolean?} hardened

lib/privatekey.js

@@ -14,6 +14,7 @@ var Random = require('./crypto/random');
  * Instantiate a PrivateKey from a BN, Buffer and WIF.
  *
  * @example
+ * ```javascript
  *
  * // generate a new random key
  * var key = PrivateKey();
@@ -26,6 +27,7 @@ var Random = require('./crypto/random');
  *
  * // instantiate from the exported (and saved) private key
  * var imported = PrivateKey.fromWIF(exported);
+ * ```
  *
  * @param {String} data - The encoded data in various formats
  * @param {String} [network] - Either "livenet" or "testnet"

lib/publickey.js

@@ -12,6 +12,7 @@ var $ = require('./util/preconditions');
  * Instantiate a PublicKey from a 'PrivateKey', 'Point', 'string', 'Buffer'.
  *
  * @example
+ * ```javascript
  *
  * // instantiate from a private key
  * var key = PublicKey(privateKey, true);
@@ -21,6 +22,7 @@ var $ = require('./util/preconditions');
  *
  * // import the public key
  * var imported = PublicKey.fromString(exported);
+ * ```
  *
  * @param {String} data - The encoded data in various formats
  * @param {Object} extra - additional options

lib/transaction/transaction.js

@@ -224,6 +224,7 @@ Transaction.prototype._newTransaction = function() {
  * SIGHASH_SINGLE or SIGHASH_NONE signatures will not be reset).
  *
  * @example
+ * ```javascript
  * var transaction = new Transaction();
  *
  * // From a pay to public key hash output from bitcoind's listunspent
@@ -235,6 +236,7 @@ Transaction.prototype._newTransaction = function() {
  * // From a multisig P2SH output
  * transaction.from({'txId': '0000...', inputIndex: 0, satoshis: 1000, script: '... OP_HASH'},
  *                  ['03000...', '02000...'], 2);
+ * ```
  *
  * @param {Object} utxo
  * @param {Array=} pubkeys

lib/transport/peer.js

@@ -16,12 +16,14 @@ var MAX_RECEIVE_BUFFER = 10000000;
  * with it using the standar messages of the bitcoin p2p protocol.
  *
  * @example
+ * ```javascript
  * 
  * var peer = new Peer('127.0.0.1').setProxy('127.0.0.1', 9050);
  * peer.on('tx', function(tx) {
  *  console.log('New transaction: ', tx.id);
  * });
  * peer.connect();
+ * ```
  *
  * @param {String} host - IP address of the remote host
  * @param {Number} [port] - Port number of the remote host

lib/transport/pool.js

@@ -18,12 +18,14 @@ function now() {
  * ongoing peer connections. Peer events are relayed to the pool.
  *
  * @example
+ * ```javascript
  *
  * var pool = new Pool(Networks.livenet);
  * pool.on('peerinv', function(peer, message) {
  *   // do something with the inventory announcement
  * });
  * pool.connect();
+ * ```
  *
  * @param {Network|String} network - The network to connect
  * @returns {Pool}

lib/transport/rpc.js

@@ -8,11 +8,13 @@ var https = require('https');
  * server and enables simple and batch RPC calls.
  *
  * @example
+ * ```javascript
  *
  * var client = new RPC('user', 'pass');
  * client.getInfo(function(err, info) {
  *   // do something with the info
  * });
+ * ```
  *
  * @param {String} user - username used to connect bitcoind
  * @param {String} password - password used to connect bitcoind

lib/unit.js

@@ -14,10 +14,12 @@ var JSUtil = require('./util/js');
  * the unit accessors.
  *
  * @example
+ * ```javascript
  *
  * var sats = Unit.fromBTC(1.3).toSatoshis();
  * var mili = Unit.fromBits(1.3).to(Unit.mBTC);
  * var btc = new Unit(1.3, Unit.bits).BTC;
+ * ```
  *
  * @param {Number} amount - The amount to be represented
  * @param {String} code - The unit of the amount

lib/uri.js

@@ -19,9 +19,11 @@ var JSUtil = require('./util/js');
  * satoshis. Any other non-standard parameters can be found under the extra member.
  *
  * @example
+ * ```javascript
  *
  * var uri = new URI('bitcoin:12A1MyfXbW6RhdRAZEqofac5jCQQjwEPBu?amount=1.2');
  * console.log(uri.address, uri.amount);
+ * ```
  *
  * @param {string|Object} data - A bitcoin URI string or an Object
  * @param {Array.<string>} [knownParams] - Required non-standard params
@@ -79,9 +81,11 @@ URI.fromJSON = function fromJSON(json) {
  * Check if an bitcoin URI string is valid
  *
  * @example
+ * ```javascript
  *
  * var valid = URI.isValid('bitcoin:12A1MyfXbW6RhdRAZEqofac5jCQQjwEPBu');
  * // true
+ * ```
  *
  * @param {string|Object} data - A bitcoin URI string or an Object
  * @param {Array.<string>} [knownParams] - Required non-standard params

package.json

@@ -95,18 +95,21 @@
     "gulp": "^3.8.10",
     "gulp-closure-compiler": "^0.2.9",
     "gulp-coveralls": "^0.1.3",
-    "gulp-jsdoc": "^0.1.4",
     "gulp-jshint": "^1.9.0",
     "gulp-mocha": "^2.0.0",
     "gulp-shell": "^0.2.10",
+    "gulp-util": "=3.0.1",
     "ink-docstrap": "git://github.com/bitpay/bitcore-jsdoctemplates.git",
     "istanbul": "^0.3.5",
+    "jsdoc-to-markdown": "=0.5.9",
     "karma": "^0.12.28",
     "karma-firefox-launcher": "^0.1.3",
     "karma-mocha": "^0.1.9",
     "mocha": "~2.0.1",
+    "more-fs": "=0.5.0",
     "run-sequence": "^1.0.2",
-    "sinon": "^1.12.2"
+    "sinon": "^1.12.2",
+    "through2": "=0.6.3"
   },
   "license": "MIT"
 }