diff --git a/.gitignore b/.gitignore index 28fe0f592..f7555ecd4 100644 --- a/.gitignore +++ b/.gitignore @@ -77,3 +77,5 @@ dist/windows dist/*.dmg dist/*.tar.gz dist/*.exe + +doc/ diff --git a/Gruntfile.js b/Gruntfile.js index d78203f5e..8844d8e30 100644 --- a/Gruntfile.js +++ b/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/directives.js', - 'js/filters.js', - 'js/routes.js', + 'js/app.js', + 'js/directives.js', + 'js/filters.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/directives.js', - 'js/filters.js', - 'js/routes.js', - 'js/services/*.js', + 'js/app.js', + 'js/directives.js', + 'js/filters.js', + 'js/routes.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']); }; diff --git a/js/models/core/HDPath.js b/js/models/core/HDPath.js index 3960284bf..041912742 100644 --- a/js/models/core/HDPath.js +++ b/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 *
* m / purpose' / copayerIndex / change:boolean / addressIndex diff --git a/js/models/core/PrivateKey.js b/js/models/core/PrivateKey.js index 8df3325c7..e8dcd8737 100644 --- a/js/models/core/PrivateKey.js +++ b/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 || {}; diff --git a/js/models/core/PublicKeyRing.js b/js/models/core/PublicKeyRing.js index 0c22694aa..54fca0faf 100644 --- a/js/models/core/PublicKeyRing.js +++ b/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)); diff --git a/js/models/core/Wallet.js b/js/models/core/Wallet.js index 6b91a8b0d..61e81b137 100644 --- a/js/models/core/Wallet.js +++ b/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 {connectionError} + * @emits publicKeyRingUpdated + * @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); diff --git a/js/models/core/WalletFactory.js b/js/models/core/WalletFactory.js index 33d763451..b91853657 100644 --- a/js/models/core/WalletFactory.js +++ b/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 */ diff --git a/jsdoc.conf.json b/jsdoc.conf.json new file mode 100644 index 000000000..5c5c11650 --- /dev/null +++ b/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" + } +} diff --git a/package.json b/package.json index dcf7345df..7248c5c0f 100644 --- a/package.json +++ b/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",