Merge pull request #1308 from eordano/grunt-jsdoc

JSDocs generated by grunt

.gitignore

@@ -77,3 +77,5 @@ dist/windows
 dist/*.dmg
 dist/*.tar.gz
 dist/*.exe
+
+doc/

Gruntfile.js

@@ -9,6 +9,7 @@ module.exports = function(grunt) {
   grunt.loadNpmTasks('grunt-contrib-concat');
   grunt.loadNpmTasks('grunt-contrib-uglify');
   grunt.loadNpmTasks('grunt-angular-gettext');
+  grunt.loadNpmTasks('grunt-jsdoc');
 
   // Project Configuration
   grunt.initConfig({
@@ -16,7 +17,7 @@ module.exports = function(grunt) {
       prod: {
         options: {
           stdout: false,
-          stderr: false 
+          stderr: false
         },
         command: 'node ./util/build.js'
       },
@@ -52,12 +53,12 @@ module.exports = function(grunt) {
       main: {
         files: [
           'js/init.js',
-          'js/app.js', 
+          'js/app.js',
-          'js/directives.js', 
+          'js/directives.js',
-          'js/filters.js', 
+          'js/filters.js',
-          'js/routes.js', 
+          'js/routes.js',
           'js/mobile.js',
-          'js/services/*.js', 
+          'js/services/*.js',
           'js/controllers/*.js'
         ],
         tasks: ['concat:main']
@@ -119,11 +120,11 @@ module.exports = function(grunt) {
       },
       main: {
         src: [
-          'js/app.js', 
+          'js/app.js',
-          'js/directives.js', 
+          'js/directives.js',
-          'js/filters.js', 
+          'js/filters.js',
-          'js/routes.js', 
+          'js/routes.js',
-          'js/services/*.js', 
+          'js/services/*.js',
           'js/controllers/*.js',
           'js/translations.js',
           'js/mobile.js', // PLACEHOLDER: CORDOVA SRIPT
@@ -172,11 +173,23 @@ module.exports = function(grunt) {
           'js/translations.js': ['po/*.po']
         }
       },
+    },
+    jsdoc: {
+      dist : {
+        src: ['js/models/core/*.js'],
+        options: {
+          destination: 'doc',
+          configure: 'jsdoc.conf.json',
+          template: './node_modules/grunt-jsdoc/node_modules/ink-docstrap/template',
+          theme: 'flatly'
+        }
+      }
     }
   });
 
+
   grunt.registerTask('default', ['shell:dev', 'nggettext_compile', 'concat', 'cssmin']);
   grunt.registerTask('prod', ['shell:prod', 'nggettext_compile', 'concat', 'cssmin', 'uglify']);
   grunt.registerTask('translate', ['nggettext_extract']);
-
+  grunt.registerTask('docs', ['jsdoc']);
 };

js/models/core/HDPath.js

@@ -7,10 +7,9 @@ var _ = require('underscore');
 
 /**
  * @namespace
- *
+ * @desc
  * HDPath contains helper functions to handle BIP32 branches as
  * Copay uses them.
- *
  * Based on https://github.com/maraoz/bips/blob/master/bip-NNNN.mediawiki
  * <pre>
  * m / purpose' / copayerIndex / change:boolean / addressIndex

js/models/core/PrivateKey.js

@@ -21,6 +21,7 @@ var HDPath = require('./HDPath');
  * @param {string} opts.extendedPrivateKeyString if set, use this private key
  *                                               string, othewise create a new
  *                                               private key
+ * @constructor
  */
 function PrivateKey(opts) {
   opts = opts || {};

js/models/core/PublicKeyRing.js

@@ -12,7 +12,7 @@ var HDPath = require('./HDPath');
 var HDParams = require('./HDParams');
 
 /**
- * @desc
+ * @desc Represents a public key ring, the set of all public keys and the used indexes
  *
  * @constructor
  * @param {Object} opts
@@ -20,10 +20,10 @@ var HDParams = require('./HDParams');
  * @param {string} opts.network 'livenet' to signal the bitcoin main network, all others are testnet
  * @param {number=} opts.requiredCopayers - defaults to 3
  * @param {number=} opts.totalCopayers - defaults to 5
- * @param {Object[]=} opts.indexes - an array to be deserialized using {@link HDParams#fromList}
+ * @param {Object[]} [opts.indexes] - an array to be deserialized using {@link HDParams#fromList}
  *                                   (defaults to all indexes in zero)
  * @param {Object=} opts.nicknameFor - nicknames for other copayers
- * @param {boolean[]=} opts.copayersBackup - whether other copayers have backed up their wallets
+ * @param {boolean[]} [opts.copayersBackup] - whether other copayers have backed up their wallets
  */
 function PublicKeyRing(opts) {
   opts = opts || {};
@@ -527,7 +527,7 @@ PublicKeyRing.prototype.getForPath = function(path) {
  * @see PublicKeyRing#getForPath
  *
  * @param {string[]} paths - the BIP32 paths
- * @return {Buffer[][]} the public keys, in buffer format
+ * @return {Array[]} the public keys, in buffer format (matrix of Buffer, Buffer[][])
  */
 PublicKeyRing.prototype.getForPaths = function(paths) {
   preconditions.checkArgument(!_.isUndefined(paths));

js/models/core/Wallet.js

@@ -53,6 +53,7 @@ var copayConfig = require('../../../config');
  * @TODO: figure out if reconnectDelay is set in milliseconds
  * @param {number} opts.reconnectDelay - amount of seconds to wait before
  *                                       attempting to reconnect
+ * @constructor
  */
 function Wallet(opts) {
   var self = this;
@@ -171,7 +172,7 @@ Wallet.prototype.seedCopayer = function(pubKey) {
  *
  * @param {string} senderId - the sender id
  * @param {Object} data - the data recived, {@see HDParams#fromList}
- * @emits {publicKeyRingUpdated}
+ * @emits publicKeyRingUpdated
  */
 Wallet.prototype._onIndexes = function(senderId, data) {
   log.debug('RECV INDEXES:', data);
@@ -216,8 +217,8 @@ Wallet.prototype.changeSettings = function(settings) {
  * @param {Object} data - the data recived, {@see HDParams#fromList}
  * @param {Object} data.publicKeyRing - data to be deserialized into a {@link PublicKeyRing}
  *                                      using {@link PublicKeyRing#fromObj}
- * @emits {publicKeyRingUpdated}
+ * @emits publicKeyRingUpdated
- * @emits {connectionError}
+ * @emits connectionError
  */
 Wallet.prototype._onPublicKeyRing = function(senderId, data) {
   log.debug('RECV PUBLICKEYRING:', data);
@@ -252,7 +253,7 @@ Wallet.prototype._onPublicKeyRing = function(senderId, data) {
  *
  * @param {string} senderId - the copayer that sent this event
  * @param {Object} m - the data received
- * @emits {txProposalEvent}
+ * @emits txProposalEvent
  */
 Wallet.prototype._processProposalEvents = function(senderId, m) {
   var ev;
@@ -955,7 +956,7 @@ Wallet.prototype.sendAllTxProposals = function(recipients, sinceTs) {
 /**
  * @desc Send a TxProposal identified by transaction id to a set of recipients
  * @param {string} ntxid - the transaction proposal id
- * @param {string[]=} recipients - the pubkeys of the recipients
+ * @param {string[]} [recipients] - the pubkeys of the recipients
  */
 Wallet.prototype.sendTxProposal = function(ntxid, recipients) {
   preconditions.checkArgument(ntxid);
@@ -997,7 +998,7 @@ Wallet.prototype.sendReject = function(ntxid) {
 
 /**
  * @desc Notify other peers that a wallet has been backed up and it's ready to be used
- * @param {string[]=} recipients - the pubkeys of the recipients
+ * @param {string[]} [recipients] - the pubkeys of the recipients
  */
 Wallet.prototype.sendWalletReady = function(recipients, sinceTs) {
   log.debug('### SENDING WalletReady TO:', recipients || 'All');
@@ -1012,7 +1013,7 @@ Wallet.prototype.sendWalletReady = function(recipients, sinceTs) {
 /**
  * @desc Notify other peers of the walletId
  * @TODO: Why is this needed? Can't everybody just calculate the walletId?
- * @param {string[]=} recipients - the pubkeys of the recipients
+ * @param {string[]} [recipients] - the pubkeys of the recipients
  */
 Wallet.prototype.sendWalletId = function(recipients) {
   log.debug('### SENDING walletId TO:', recipients || 'All', this.id);
@@ -1027,7 +1028,7 @@ Wallet.prototype.sendWalletId = function(recipients) {
 
 /**
  * @desc Send the current PublicKeyRing to other recipients
- * @param {string[]=} recipients - the pubkeys of the recipients
+ * @param {string[]} [recipients] - the pubkeys of the recipients
  */
 Wallet.prototype.sendPublicKeyRing = function(recipients) {
   log.debug('### SENDING publicKeyRing TO:', recipients || 'All', this.publicKeyRing.toObj());
@@ -1042,7 +1043,7 @@ Wallet.prototype.sendPublicKeyRing = function(recipients) {
 
 /**
  * @desc Send the current indexes of our public key ring to other peers
- * @param {string[]=} recipients - the pubkeys of the recipients
+ * @param {string[]} recipients - the pubkeys of the recipients
  */
 Wallet.prototype.sendIndexes = function(recipients) {
   var indexes = HDParams.serialize(this.publicKeyRing.indexes);
@@ -1057,7 +1058,7 @@ Wallet.prototype.sendIndexes = function(recipients) {
 
 /**
  * @desc Send our addressBook to other recipients
- * @param {string[]=} recipients - the pubkeys of the recipients
+ * @param {string[]} recipients - the pubkeys of the recipients
  */
 Wallet.prototype.sendAddressBook = function(recipients) {
   log.debug('### SENDING addressBook TO:', recipients || 'All', this.addressBook);

js/models/core/WalletFactory.js

@@ -30,6 +30,7 @@ var preconditions = require('preconditions').singleton();
  * @param {Object} config.wallet - default configuration for the wallet
  * @TODO: put `version` inside of the config object
  * @param {string} version - the version of copay for which this wallet was generated (for example, 0.4.7)
+ * @constructor
  */
 function WalletFactory(config, version) {
   var self = this;
@@ -318,7 +319,7 @@ WalletFactory.prototype.decodeSecret = function(secret) {
 
 /**
  * @callback walletCreationCallback
- * @param {?=} err - an error, if any, that happened during the wallet creation
+ * @param {?} err - an error, if any, that happened during the wallet creation
  * @param {Wallet=} wallet - the wallet created
  */
 

jsdoc.conf.json

@@ -0,0 +1,18 @@
+{
+    "tags": {
+        "allowUnknownTags": true
+    },
+    "source": {
+        "includePattern": ".+\\.js(doc)?$",
+        "excludePattern": "(^|\\/|\\\\)_"
+    },
+    "plugins": [],
+    "templates": {
+        "cleverLinks": false,
+        "monospaceLinks": false,
+        "default": {
+            "outputSourceFiles": true
+        },
+        "theme": "flatly"
+    }
+}

package.json

@@ -55,17 +55,18 @@
     "express": "4.0.0",
     "github-releases": "0.2.0",
     "grunt": "^0.4.5",
+    "grunt-angular-gettext": "^0.2.15",
     "grunt-browserify": "2.0.8",
     "grunt-cli": "^0.1.13",
     "grunt-contrib-concat": "0.5.0",
     "grunt-contrib-cssmin": "0.10.0",
     "grunt-contrib-uglify": "^0.5.1",
     "grunt-contrib-watch": "0.5.3",
+    "grunt-jsdoc": "^0.5.7",
     "grunt-markdown": "0.5.0",
     "bitcore": "0.1.36",
     "grunt-mocha-test": "0.8.2",
     "grunt-shell": "0.6.4",
-    "grunt-angular-gettext": "^0.2.15",
     "istanbul": "0.2.10",
     "karma": "0.12.9",
     "karma-chrome-launcher": "0.1.3",