From 6d42e017184f9633c80f44df641592a7b0cd85a8 Mon Sep 17 00:00:00 2001 From: Braydon Fuller Date: Thu, 18 Dec 2014 11:41:09 -0500 Subject: [PATCH 1/4] Fix formatting issue with examples --- lib/address.js | 6 ++++++ lib/hdprivatekey.js | 2 ++ lib/hdpublickey.js | 2 ++ lib/privatekey.js | 2 ++ lib/publickey.js | 2 ++ lib/transaction/transaction.js | 2 ++ lib/transport/peer.js | 2 ++ lib/transport/pool.js | 2 ++ lib/transport/rpc.js | 2 ++ lib/unit.js | 2 ++ lib/uri.js | 4 ++++ 11 files changed, 28 insertions(+) diff --git a/lib/address.js b/lib/address.js index f60fc42..88c8616 100644 --- a/lib/address.js +++ b/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' diff --git a/lib/hdprivatekey.js b/lib/hdprivatekey.js index 69ed415..877f880 100644 --- a/lib/hdprivatekey.js +++ b/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 diff --git a/lib/hdpublickey.js b/lib/hdpublickey.js index 8599556..0dc3f50 100644 --- a/lib/hdpublickey.js +++ b/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 diff --git a/lib/privatekey.js b/lib/privatekey.js index eaecd00..4a2cced 100644 --- a/lib/privatekey.js +++ b/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" diff --git a/lib/publickey.js b/lib/publickey.js index 58e51b7..26166c1 100644 --- a/lib/publickey.js +++ b/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 diff --git a/lib/transaction/transaction.js b/lib/transaction/transaction.js index 00a64e1..74bf16a 100644 --- a/lib/transaction/transaction.js +++ b/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 diff --git a/lib/transport/peer.js b/lib/transport/peer.js index aea73bd..1c10f1b 100644 --- a/lib/transport/peer.js +++ b/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 diff --git a/lib/transport/pool.js b/lib/transport/pool.js index d99033a..ec2b64c 100644 --- a/lib/transport/pool.js +++ b/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} diff --git a/lib/transport/rpc.js b/lib/transport/rpc.js index 6fcee3f..b297ae5 100644 --- a/lib/transport/rpc.js +++ b/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 diff --git a/lib/unit.js b/lib/unit.js index ba6baac..50c6996 100644 --- a/lib/unit.js +++ b/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 diff --git a/lib/uri.js b/lib/uri.js index 54b4405..940c813 100644 --- a/lib/uri.js +++ b/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.} [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.} [knownParams] - Required non-standard params From f77b1cd62c97033ef77dd12b5d5f8754faca4a58 Mon Sep 17 00:00:00 2001 From: Braydon Fuller Date: Thu, 18 Dec 2014 17:02:52 -0500 Subject: [PATCH 2/4] Moved docs to match organization and naming of `lib` (mostly) --- docs/{helpers => }/Networks.md | 0 docs/{helpers => }/PaymentProtocol.md | 0 docs/{models/Address.md => address.md} | 0 docs/{models/Block.md => block.md} | 0 docs/config.json | 6 ------ docs/{helpers/Crypto.md => crypto.md} | 0 docs/{helpers/ECIES.md => ecies.md} | 0 docs/{helpers/Encoding.md => encoding.md} | 0 docs/{models/Hierarchical.md => hierarchical.md} | 0 docs/{networking/JSONRPC.md => jsonrpc.md} | 0 docs/{networking/Peer.md => peer.md} | 0 docs/{networking/Pool.md => pool.md} | 0 docs/{models/PrivateKey.md => privatekey.md} | 0 docs/{models/PublicKey.md => publickey.md} | 0 docs/{models/Script.md => script.md} | 0 docs/{models/Transaction.md => transaction.md} | 0 docs/{helpers/Unit.md => unit.md} | 0 docs/{helpers/URI.md => uri.md} | 0 gulpfile.js | 2 +- package.json | 2 +- 20 files changed, 2 insertions(+), 8 deletions(-) rename docs/{helpers => }/Networks.md (100%) rename docs/{helpers => }/PaymentProtocol.md (100%) rename docs/{models/Address.md => address.md} (100%) rename docs/{models/Block.md => block.md} (100%) delete mode 100644 docs/config.json rename docs/{helpers/Crypto.md => crypto.md} (100%) rename docs/{helpers/ECIES.md => ecies.md} (100%) rename docs/{helpers/Encoding.md => encoding.md} (100%) rename docs/{models/Hierarchical.md => hierarchical.md} (100%) rename docs/{networking/JSONRPC.md => jsonrpc.md} (100%) rename docs/{networking/Peer.md => peer.md} (100%) rename docs/{networking/Pool.md => pool.md} (100%) rename docs/{models/PrivateKey.md => privatekey.md} (100%) rename docs/{models/PublicKey.md => publickey.md} (100%) rename docs/{models/Script.md => script.md} (100%) rename docs/{models/Transaction.md => transaction.md} (100%) rename docs/{helpers/Unit.md => unit.md} (100%) rename docs/{helpers/URI.md => uri.md} (100%) diff --git a/docs/helpers/Networks.md b/docs/Networks.md similarity index 100% rename from docs/helpers/Networks.md rename to docs/Networks.md diff --git a/docs/helpers/PaymentProtocol.md b/docs/PaymentProtocol.md similarity index 100% rename from docs/helpers/PaymentProtocol.md rename to docs/PaymentProtocol.md diff --git a/docs/models/Address.md b/docs/address.md similarity index 100% rename from docs/models/Address.md rename to docs/address.md diff --git a/docs/models/Block.md b/docs/block.md similarity index 100% rename from docs/models/Block.md rename to docs/block.md diff --git a/docs/config.json b/docs/config.json deleted file mode 100644 index 76f478a..0000000 --- a/docs/config.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "useSideMenu": true, - "lineBreaks": "gfm", - "additionalFooterText": "Bitcore™ © 2013-2014 BitPay, Inc. Bitcore is released under the MIT license. ", - "anchorCharacter": "#" -} \ No newline at end of file diff --git a/docs/helpers/Crypto.md b/docs/crypto.md similarity index 100% rename from docs/helpers/Crypto.md rename to docs/crypto.md diff --git a/docs/helpers/ECIES.md b/docs/ecies.md similarity index 100% rename from docs/helpers/ECIES.md rename to docs/ecies.md diff --git a/docs/helpers/Encoding.md b/docs/encoding.md similarity index 100% rename from docs/helpers/Encoding.md rename to docs/encoding.md diff --git a/docs/models/Hierarchical.md b/docs/hierarchical.md similarity index 100% rename from docs/models/Hierarchical.md rename to docs/hierarchical.md diff --git a/docs/networking/JSONRPC.md b/docs/jsonrpc.md similarity index 100% rename from docs/networking/JSONRPC.md rename to docs/jsonrpc.md diff --git a/docs/networking/Peer.md b/docs/peer.md similarity index 100% rename from docs/networking/Peer.md rename to docs/peer.md diff --git a/docs/networking/Pool.md b/docs/pool.md similarity index 100% rename from docs/networking/Pool.md rename to docs/pool.md diff --git a/docs/models/PrivateKey.md b/docs/privatekey.md similarity index 100% rename from docs/models/PrivateKey.md rename to docs/privatekey.md diff --git a/docs/models/PublicKey.md b/docs/publickey.md similarity index 100% rename from docs/models/PublicKey.md rename to docs/publickey.md diff --git a/docs/models/Script.md b/docs/script.md similarity index 100% rename from docs/models/Script.md rename to docs/script.md diff --git a/docs/models/Transaction.md b/docs/transaction.md similarity index 100% rename from docs/models/Transaction.md rename to docs/transaction.md diff --git a/docs/helpers/Unit.md b/docs/unit.md similarity index 100% rename from docs/helpers/Unit.md rename to docs/unit.md diff --git a/docs/helpers/URI.md b/docs/uri.md similarity index 100% rename from docs/helpers/URI.md rename to docs/uri.md diff --git a/gulpfile.js b/gulpfile.js index aa12152..adcbf43 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -126,7 +126,7 @@ 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', shell.task(['node_modules/.bin/jsdoc2md lib/address.js > docs/api/address.md'])); gulp.task('coverage', shell.task(['node_modules/.bin/./istanbul cover node_modules/.bin/_mocha -- --recursive'])); diff --git a/package.json b/package.json index f49dd53..b2a8e99 100644 --- a/package.json +++ b/package.json @@ -95,12 +95,12 @@ "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", "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", From f89612f9de9adb3ab4745d9c50903a6128ffd33f Mon Sep 17 00:00:00 2001 From: Braydon Fuller Date: Thu, 18 Dec 2014 18:38:47 -0500 Subject: [PATCH 3/4] Added jsdoc2md to generate api reference documentation to markdown, and organized docs into 'api' and 'guide' --- docs/{ => guide}/address.md | 0 docs/{ => guide}/block.md | 0 docs/{ => guide}/crypto.md | 0 docs/{ => guide}/ecies.md | 0 docs/{ => guide}/encoding.md | 0 docs/{ => guide}/examples.md | 0 docs/{ => guide}/hierarchical.md | 0 docs/{ => guide}/index.md | 0 docs/{ => guide}/jsonrpc.md | 0 docs/{ => guide}/navigation.md | 0 docs/{Networks.md => guide/networks.md} | 0 .../paymentprotocol.md} | 0 docs/{ => guide}/peer.md | 0 docs/{ => guide}/pool.md | 0 docs/{ => guide}/privatekey.md | 0 docs/{ => guide}/publickey.md | 0 docs/{ => guide}/script.md | 0 docs/{ => guide}/transaction.md | 0 docs/{ => guide}/unit.md | 0 docs/{ => guide}/uri.md | 0 gulpfile.js | 32 +++++++++++++++++-- package.json | 5 ++- 22 files changed, 34 insertions(+), 3 deletions(-) rename docs/{ => guide}/address.md (100%) rename docs/{ => guide}/block.md (100%) rename docs/{ => guide}/crypto.md (100%) rename docs/{ => guide}/ecies.md (100%) rename docs/{ => guide}/encoding.md (100%) rename docs/{ => guide}/examples.md (100%) rename docs/{ => guide}/hierarchical.md (100%) rename docs/{ => guide}/index.md (100%) rename docs/{ => guide}/jsonrpc.md (100%) rename docs/{ => guide}/navigation.md (100%) rename docs/{Networks.md => guide/networks.md} (100%) rename docs/{PaymentProtocol.md => guide/paymentprotocol.md} (100%) rename docs/{ => guide}/peer.md (100%) rename docs/{ => guide}/pool.md (100%) rename docs/{ => guide}/privatekey.md (100%) rename docs/{ => guide}/publickey.md (100%) rename docs/{ => guide}/script.md (100%) rename docs/{ => guide}/transaction.md (100%) rename docs/{ => guide}/unit.md (100%) rename docs/{ => guide}/uri.md (100%) diff --git a/docs/address.md b/docs/guide/address.md similarity index 100% rename from docs/address.md rename to docs/guide/address.md diff --git a/docs/block.md b/docs/guide/block.md similarity index 100% rename from docs/block.md rename to docs/guide/block.md diff --git a/docs/crypto.md b/docs/guide/crypto.md similarity index 100% rename from docs/crypto.md rename to docs/guide/crypto.md diff --git a/docs/ecies.md b/docs/guide/ecies.md similarity index 100% rename from docs/ecies.md rename to docs/guide/ecies.md diff --git a/docs/encoding.md b/docs/guide/encoding.md similarity index 100% rename from docs/encoding.md rename to docs/guide/encoding.md diff --git a/docs/examples.md b/docs/guide/examples.md similarity index 100% rename from docs/examples.md rename to docs/guide/examples.md diff --git a/docs/hierarchical.md b/docs/guide/hierarchical.md similarity index 100% rename from docs/hierarchical.md rename to docs/guide/hierarchical.md diff --git a/docs/index.md b/docs/guide/index.md similarity index 100% rename from docs/index.md rename to docs/guide/index.md diff --git a/docs/jsonrpc.md b/docs/guide/jsonrpc.md similarity index 100% rename from docs/jsonrpc.md rename to docs/guide/jsonrpc.md diff --git a/docs/navigation.md b/docs/guide/navigation.md similarity index 100% rename from docs/navigation.md rename to docs/guide/navigation.md diff --git a/docs/Networks.md b/docs/guide/networks.md similarity index 100% rename from docs/Networks.md rename to docs/guide/networks.md diff --git a/docs/PaymentProtocol.md b/docs/guide/paymentprotocol.md similarity index 100% rename from docs/PaymentProtocol.md rename to docs/guide/paymentprotocol.md diff --git a/docs/peer.md b/docs/guide/peer.md similarity index 100% rename from docs/peer.md rename to docs/guide/peer.md diff --git a/docs/pool.md b/docs/guide/pool.md similarity index 100% rename from docs/pool.md rename to docs/guide/pool.md diff --git a/docs/privatekey.md b/docs/guide/privatekey.md similarity index 100% rename from docs/privatekey.md rename to docs/guide/privatekey.md diff --git a/docs/publickey.md b/docs/guide/publickey.md similarity index 100% rename from docs/publickey.md rename to docs/guide/publickey.md diff --git a/docs/script.md b/docs/guide/script.md similarity index 100% rename from docs/script.md rename to docs/guide/script.md diff --git a/docs/transaction.md b/docs/guide/transaction.md similarity index 100% rename from docs/transaction.md rename to docs/guide/transaction.md diff --git a/docs/unit.md b/docs/guide/unit.md similarity index 100% rename from docs/unit.md rename to docs/guide/unit.md diff --git a/docs/uri.md b/docs/guide/uri.md similarity index 100% rename from docs/uri.md rename to docs/guide/uri.md diff --git a/gulpfile.js b/gulpfile.js index adcbf43..eb9519b 100644 --- a/gulpfile.js +++ b/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(['node_modules/.bin/jsdoc2md lib/address.js > docs/api/address.md'])); +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'])); diff --git a/package.json b/package.json index b2a8e99..2138bec 100644 --- a/package.json +++ b/package.json @@ -98,6 +98,7 @@ "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", @@ -105,8 +106,10 @@ "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" } From e6eddc62e99f3574db15455a03a6f38b8b57ce32 Mon Sep 17 00:00:00 2001 From: Braydon Fuller Date: Thu, 18 Dec 2014 18:42:35 -0500 Subject: [PATCH 4/4] Set version numbers --- package.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/package.json b/package.json index 2138bec..ec059bf 100644 --- a/package.json +++ b/package.json @@ -98,7 +98,7 @@ "gulp-jshint": "^1.9.0", "gulp-mocha": "^2.0.0", "gulp-shell": "^0.2.10", - "gulp-util": "^3.0.1", + "gulp-util": "=3.0.1", "ink-docstrap": "git://github.com/bitpay/bitcore-jsdoctemplates.git", "istanbul": "^0.3.5", "jsdoc-to-markdown": "=0.5.9", @@ -106,10 +106,10 @@ "karma-firefox-launcher": "^0.1.3", "karma-mocha": "^0.1.9", "mocha": "~2.0.1", - "more-fs": "^0.5.0", + "more-fs": "=0.5.0", "run-sequence": "^1.0.2", "sinon": "^1.12.2", - "through2": "^0.6.3" + "through2": "=0.6.3" }, "license": "MIT" }