Refactor gulpfile

gulpfile.js

@@ -3,10 +3,29 @@
  *
  * Defines tasks that can be run on gulp.
  *
- * Summary:
+ * Summary: <ul>
- *  * test - Run tests
+ * <li> `test` - runs all the tests on node and the browser (mocha and karma)
- *  * watch:test - Waits for filesystem changes and runs tests
+ * <ul>
- *
+ * <li> `test:node`
+ * <li> `test:node:nofail` - internally used for watching (due to bug on gulp-mocha)
+ * <li> `test:browser`
+ * </ul>`
+ * <li> `watch:test` - watch for file changes and run tests
+ * <ul>
+ * <li> `watch:test:node`
+ * <li> `watch:test:browser`
+ * </ul>`
+ * <li> `browser` - generate files needed for browser (browserify)
+ * <ul>
+ * <li> `browser:uncompressed` - build `browser/bitcore.js`
+ * <li> `browser:compressed` - build `browser/bitcore.min.js`
+ * <li> `browser:maketests` - build `browser/tests.js`, needed for testing without karma
+ * </ul>`
+ * <li> `errors` - autogenerate the `./lib/errors/index.js` file with error definitions 
+ * <li> `lint` - run `jshint`
+ * <li> `coverage` - run `istanbul` with mocha to generate a report of test coverage
+ * <li> `jsdoc` - run `jsdoc` to generate the API reference
+ * </ul>
  */
 'use strict';
 
@@ -41,39 +60,70 @@ var testKarma = shell.task([
   './node_modules/karma/bin/karma start --single-run --browsers Firefox'
 ]);
 
+/**
+ * Testing
+ */
 
-gulp.task('test', ['errors'], testMocha);
+gulp.task('test:node', ['errors'], testMocha);
 
-gulp.task('test-all', ['errors'], function(callback) {
+gulp.task('test:node:nofail', ['errors'], function() {
-  runSequence(['test'], ['karma'], callback);
-});
-
-gulp.task('test-nofail', ['errors'], function() {
   return testMocha().on('error', ignoreError);
 });
 
-gulp.task('watch:test', function() {
+gulp.task('test:browser', ['browser:uncompressed', 'browser:maketests'], testKarma);
-  // TODO: Only run tests that are linked to file changes by doing
+
-  // something smart like reading through the require statements
+gulp.task('test', function(callback) {
-  return gulp.watch(alljs, ['test-nofail']);
+  runSequence(['test:node'], ['test:browser'], callback);
 });
 
-gulp.task('watch:coverage', function() {
+/**
-  // TODO: Only run tests that are linked to file changes by doing
+ * File generation
-  // something smart like reading through the require statements
+ */
-  return gulp.watch(alljs, ['coverage']);
+
+gulp.task('browser:uncompressed', ['errors'], shell.task([
+  './node_modules/.bin/browserify index.js --insert-global-vars=true --standalone=bitcore -o browser/bitcore.js'
+]));
+
+gulp.task('browser:compressed', ['errors'], function() {
+  return gulp.src('dist/bitcore.js')
+    .pipe(closureCompiler({
+      fileName: 'bitcore.min.js',
+      compilerPath: 'node_modules/closure-compiler-jar/compiler.jar',
+      compilerFlags: {
+        language_in: 'ECMASCRIPT5',
+        jscomp_off: 'suspiciousCode'
+      }
+    }))
+    .pipe(gulp.dest('dist'));
 });
 
-gulp.task('watch:lint', function() {
+gulp.task('browser:maketests', shell.task([
-  // TODO: Only lint files that are linked to file changes by doing
+  'find test/ -type f -name "*.js" | xargs ./node_modules/.bin/browserify -t brfs -o browser/tests.js'
-  // something smart like reading through the require statements
+]));
-  return gulp.watch(alljs, ['lint']);
+
+gulp.task('browser', ['errors'], function(callback) {
+  runSequence(['browser:uncompressed'], ['browser:compressed'], ['browser:maketests'], callback);
 });
 
-gulp.task('watch:browser', function() {
+gulp.task('errors', shell.task([
-  return gulp.watch(alljs, ['browser-all']);
+  'node ./lib/errors/build.js'
+]));
+
+
+/**
+ * Code quality and documentation
+ */
+
+gulp.task('lint', function() {
+  return gulp.src(alljs)
+    .pipe(jshint())
+    .pipe(jshint.reporter('default'));
 });
 
+gulp.task('plato', shell.task[
+  'plato -d report -r -l .jshintrc -t bitcore lib'
+]);
+
 gulp.task('coverage', shell.task(['istanbul cover _mocha -- --recursive']));
 
 gulp.task('jsdoc', function() {
@@ -81,7 +131,8 @@ gulp.task('jsdoc', function() {
     .pipe(jsdoc.parser({
       name: 'bitcore',
       version: '0.8.0',
-      description: 'API Reference for the bitcore bitcoin javascript library'
+      description: 'API Reference for the bitcore bitcoin javascript library',
+      plugins: ['plugins/markdown']
     }))
     .pipe(jsdoc.generator('./apiref', {
       path: 'ink-docstrap',
@@ -89,50 +140,56 @@ gulp.task('jsdoc', function() {
     }));
 });
 
-gulp.task('lint', function() {
+/**
-  return gulp.src(alljs)
+ * Watch tasks
-    .pipe(jshint())
+ */
-    .pipe(jshint.reporter('default'));
-});
 
-gulp.task('browser', ['errors'], shell.task([
+gulp.task('watch:test', function() {
-  './node_modules/.bin/browserify index.js --insert-global-vars=true --standalone=bitcore -o browser/bitcore.js'
+  // TODO: Only run tests that are linked to file changes by doing
-]));
+  // something smart like reading through the require statements
+  return gulp.watch(alljs, ['test']);
+});
 
-gulp.task('browser-test', shell.task([
+gulp.task('watch:test:node', function() {
-  'find test/ -type f -name "*.js" | xargs ./node_modules/.bin/browserify -t brfs -o browser/tests.js'
+  // TODO: Only run tests that are linked to file changes by doing
-]));
+  // something smart like reading through the require statements
+  return gulp.watch(alljs, ['test:node']);
+});
 
-gulp.task('browser-all', ['errors'], function(callback) {
+gulp.task('watch:test:browser', function() {
-  runSequence(['browser'], ['browser-test'], callback);
+  // TODO: Only run tests that are linked to file changes by doing
+  // something smart like reading through the require statements
+  return gulp.watch(alljs, ['test:browser']);
 });
 
-gulp.task('karma', ['browser-all'], testKarma);
+gulp.task('watch:jsdoc', function() {
+  // TODO: Only run tests that are linked to file changes by doing
+  // something smart like reading through the require statements
+  return gulp.watch(alljs, ['jsdoc']);
+});
 
-gulp.task('plato', shell.task[
+gulp.task('watch:coverage', function() {
-  'plato -d report -r -l .jshintrc -t bitcore lib'
+  // TODO: Only run tests that are linked to file changes by doing
-]);
+  // something smart like reading through the require statements
+  return gulp.watch(alljs, ['coverage']);
+});
 
-gulp.task('errors', shell.task([
+gulp.task('watch:lint', function() {
-  'node ./lib/errors/build.js'
+  // TODO: Only lint files that are linked to file changes by doing
-]));
+  // something smart like reading through the require statements
+  return gulp.watch(alljs, ['lint']);
+});
 
-gulp.task('minify', ['errors'], function() {
+gulp.task('watch:browser', function() {
-  return gulp.src('dist/bitcore.js')
+  return gulp.watch(alljs, ['browser']);
-    .pipe(closureCompiler({
-      fileName: 'bitcore.min.js',
-      compilerPath: 'node_modules/closure-compiler-jar/compiler.jar',
-      compilerFlags: {
-        language_in: 'ECMASCRIPT5',
-        jscomp_off: 'suspiciousCode'
-      }
-    }))
-    .pipe(gulp.dest('dist'));
 });
 
+/**
+ * Default task
+ */
 gulp.task('default', function(callback) {
   return runSequence(['lint', 'jsdoc'],
-                     ['browser', 'test'],
+                     ['browser:compressed', 'test'],
                      ['coverage', 'minify'],
                      callback);
 });

lib/address.js

@@ -8,10 +8,16 @@ var JSUtil = require('./util/js');
 
 /**
  * Instantiate an address from an address String or Buffer, a public key or script hash Buffer,
- * or an instance of PublicKey or Script.
+ * or an instance of {@link PublicKey} or {@link Script}.
  *
- * @example
+ * This is an immutable class, and if the first parameter provided to this constructor is an
+ * `Address` instance, the same argument will be returned.
+ *
+ * An address has two key properties: `network` and `type`. The type is either
+ * `Address.PayToPublicKeyHash` (value is the `'pubkeyhash'` string)
+ * or `Address.PayToScriptHash` (the string `'scripthash'`). The network is an instance of {@link Network}.
  *
+ * @example
  * // validate that an input field is valid
  * var error = Address.getValidationError(input, 'testnet');
  * if (!error) {
@@ -24,9 +30,8 @@ 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 {String} data - The encoded data in various formats
+ * @param {Network|String|number} [network] - The network: 'livenet' or 'testnet'
- * @param {String} [network] - The network: 'livenet' or 'testnet'
  * @param {String} [type] - The type of address: 'script' or 'pubkey'
  * @returns {Address} A new valid and frozen instance of an Address
  * @constructor
@@ -90,7 +95,12 @@ function Address(data, network, type) {
   return this;
 }
 
+/** @static */
 Address.PayToPublicKeyHash = 'pubkeyhash';
+/**
+ * @static
+ * @value 'scripthash'
+ */
 Address.PayToScriptHash = 'scripthash';
 
 /**

lib/block.js

@@ -16,17 +16,17 @@ var Varint = require('./encoding/varint');
  * the properties of the Block
  *
  * @param {*} - A Buffer, JSON string, or Object
- * @returns {Block} - An instance of Block
+ * @returns {Block}
  * @constructor
  */
-var Block = function Block(arg) {
+function Block(arg) {
   if (!(this instanceof Block)) {
     return new Block(arg);
   }
   _.extend(this, Block._from(arg));
   this._setupProperties();
   return this;
-};
+}
 
 /**
  * @param {*} - A Buffer, JSON string or Object

lib/hdprivatekey.js

@@ -398,20 +398,20 @@ HDPrivateKey.prototype.inspect = function() {
 /**
  * Returns a plain object with a representation of this private key.
  *
- * Fields include:
+ * Fields include:<ul>
- *  * network: either 'livenet' or 'testnet'
+ * <li> network: either 'livenet' or 'testnet'
- *  * depth: a number ranging from 0 to 255
+ * <li> depth: a number ranging from 0 to 255
- *  * fingerPrint: a number ranging from 0 to 2^32-1, taken from the hash of the
+ * <li> fingerPrint: a number ranging from 0 to 2^32-1, taken from the hash of the
- *        associated public key
+ * <li>     associated public key
- *  * parentFingerPrint: a number ranging from 0 to 2^32-1, taken from the hash
+ * <li> parentFingerPrint: a number ranging from 0 to 2^32-1, taken from the hash
- *        of this parent's associated public key or zero.
+ * <li>     of this parent's associated public key or zero.
- *  * childIndex: the index from which this child was derived (or zero)
+ * <li> childIndex: the index from which this child was derived (or zero)
- *  * chainCode: an hexa string representing a number used in the derivation
+ * <li> chainCode: an hexa string representing a number used in the derivation
- *  * privateKey: the private key associated, in hexa representation
+ * <li> privateKey: the private key associated, in hexa representation
- *  * xprivkey: the representation of this extended private key in checksum
+ * <li> xprivkey: the representation of this extended private key in checksum
- *        base58 format
+ * <li>     base58 format
- *  * checksum: the base58 checksum of xprivkey
+ * <li> checksum: the base58 checksum of xprivkey
- *
+ * </ul>
  *  @return {Object}
  */
 HDPrivateKey.prototype.toObject = function toObject() {

lib/hdpublickey.js

@@ -361,18 +361,19 @@ HDPublicKey.prototype.inspect = function() {
 /**
  * Returns a plain javascript object with information to reconstruct a key.
  *
- * Fields are:
+ * Fields are: <ul>
- *  * network: 'livenet' or 'testnet'
+ *  <li> network: 'livenet' or 'testnet'
- *  * depth: a number from 0 to 255, the depth to the master extended key
+ *  <li> depth: a number from 0 to 255, the depth to the master extended key
- *  * fingerPrint: a number of 32 bits taken from the hash of the public key
+ *  <li> fingerPrint: a number of 32 bits taken from the hash of the public key
- *  * fingerPrint: a number of 32 bits taken from the hash of this key's
+ *  <li> fingerPrint: a number of 32 bits taken from the hash of this key's
- *        parent's public key
+ *  <li>     parent's public key
- *  * childIndex: index with which this key was derived
+ *  <li> childIndex: index with which this key was derived
- *  * chainCode: string in hexa encoding used for derivation
+ *  <li> chainCode: string in hexa encoding used for derivation
- *  * publicKey: string, hexa encoded, in compressed key format
+ *  <li> publicKey: string, hexa encoded, in compressed key format
- *  * checksum: BufferUtil.integerFromBuffer(this._buffers.checksum),
+ *  <li> checksum: BufferUtil.integerFromBuffer(this._buffers.checksum),
- *  * xpubkey: the string with the base58 representation of this extended key
+ *  <li> xpubkey: the string with the base58 representation of this extended key
- *  * checksum: the base58 checksum of xpubkey
+ *  <li> checksum: the base58 checksum of xpubkey
+ * </ul>
  */
 HDPublicKey.prototype.toObject = function toObject() {
   return {
@@ -388,6 +389,10 @@ HDPublicKey.prototype.toObject = function toObject() {
   };
 };
 
+/**
+ * Serializes this object into a JSON string
+ * @return {string}
+ */
 HDPublicKey.prototype.toJSON = function toJSON() {
   return JSON.stringify(this.toObject());
 };