From c9f83fe8bc60a87876242a2dfb5350fceafffca1 Mon Sep 17 00:00:00 2001 From: bitpshr Date: Wed, 18 Apr 2018 17:02:08 -0400 Subject: Add JSDoc to various background scripts --- app/scripts/config.js | 39 ++++++++++- app/scripts/contentscript.js | 42 ++++++++++++ app/scripts/edge-encryptor.js | 142 ++++++++++++++++++++++++---------------- app/scripts/first-time-state.js | 16 +++-- app/scripts/inpage.js | 11 ++-- app/scripts/popup-core.js | 25 ++++++- 6 files changed, 205 insertions(+), 70 deletions(-) (limited to 'app/scripts') diff --git a/app/scripts/config.js b/app/scripts/config.js index a8470ed82..634d7a013 100644 --- a/app/scripts/config.js +++ b/app/scripts/config.js @@ -15,7 +15,41 @@ const BETA_UI_NETWORK_TYPE = 'networkBeta' global.METAMASK_DEBUG = process.env.METAMASK_DEBUG -module.exports = { +/** + * @typedef {Object} UrlConfig + * @property {string} localhost URL of local RPC provider + * @property {string} mainnet URL of mainnet RPC provider + * @property {string} ropsten URL of Ropsten testnet RPC provider + * @property {string} kovan URL of Kovan testnet RPC provider + * @property {string} rinkeby URL of Rinkeby testnet RPC provider + */ + +/** + * @typedef {Object} NameConfig + * @property {string} 3 URL of local RPC provider + * @property {string} 4 URL of mainnet RPC provider + * @property {string} 42 URL of Ropsten testnet RPC provider + */ + +/** + * @typedef {Object} EnumConfig + * @property {string} DEFAULT_RPC Default network provider URL + * @property {string} OLD_UI_NETWORK_TYPE + * @property {string} BETA_UI_NETWORK_TYPE + */ + +/** + * @typedef {Object} Config + * @property {UrlConfig} network Network configuration parameters + * @property {UrlConfig} networkBeta Beta UI network configuration parameters + * @property {NameConfig} networkNames Network name configuration parameters + * @property {EnumConfig} enums Application-wide string constants + */ + +/** + * @type {Config} Application configuration object + **/ +const config = { network: { localhost: LOCALHOST_RPC_URL, mainnet: MAINET_RPC_URL, @@ -23,7 +57,6 @@ module.exports = { kovan: KOVAN_RPC_URL, rinkeby: RINKEBY_RPC_URL, }, - // Used for beta UI networkBeta: { localhost: LOCALHOST_RPC_URL, mainnet: MAINET_RPC_URL_BETA, @@ -42,3 +75,5 @@ module.exports = { BETA_UI_NETWORK_TYPE, }, } + +module.exports = config \ No newline at end of file diff --git a/app/scripts/contentscript.js b/app/scripts/contentscript.js index fe1766273..728aab8cb 100644 --- a/app/scripts/contentscript.js +++ b/app/scripts/contentscript.js @@ -23,6 +23,9 @@ if (shouldInjectWeb3()) { setupStreams() } +/** + * Creates a script tag that injects inpage.js + */ function setupInjection () { try { // inject in-page script @@ -37,6 +40,10 @@ function setupInjection () { } } +/** + * Sets up two-way communication streams between the + * browser extension and local per-page browser context + */ function setupStreams () { // setup communication to page and plugin const pageStream = new LocalMessageDuplexStream({ @@ -89,17 +96,34 @@ function setupStreams () { mux.ignoreStream('publicConfig') } + +/** + * Error handler for page to plugin stream disconnections + * + * @param {string} remoteLabel Remote stream name + * @param {Error} err Stream connection error + */ function logStreamDisconnectWarning (remoteLabel, err) { let warningMsg = `MetamaskContentscript - lost connection to ${remoteLabel}` if (err) warningMsg += '\n' + err.stack console.warn(warningMsg) } +/** + * Determines if Web3 should be injected + * + * @returns {boolean} True of Web3 should be injected + */ function shouldInjectWeb3 () { return doctypeCheck() && suffixCheck() && documentElementCheck() && !blacklistedDomainCheck() } +/** + * Checks the doctype of the current document if it exists + * + * @returns {boolean} True if the doctype is html or if none exists + */ function doctypeCheck () { const doctype = window.document.doctype if (doctype) { @@ -109,6 +133,11 @@ function doctypeCheck () { } } +/** + * Checks the current document extension + * + * @returns {boolean} True if the current extension is not prohibited + */ function suffixCheck () { var prohibitedTypes = ['xml', 'pdf'] var currentUrl = window.location.href @@ -122,6 +151,11 @@ function suffixCheck () { return true } +/** + * Checks the documentElement of the current document + * + * @returns {boolean} True if the documentElement is an html node or if none exists + */ function documentElementCheck () { var documentElement = document.documentElement.nodeName if (documentElement) { @@ -130,6 +164,11 @@ function documentElementCheck () { return true } +/** + * Checks if the current domain is blacklisted + * + * @returns {boolean} True if the current domain is blacklisted + */ function blacklistedDomainCheck () { var blacklistedDomains = [ 'uscourts.gov', @@ -148,6 +187,9 @@ function blacklistedDomainCheck () { return false } +/** + * Redirects the current page to a phishing information page + */ function redirectToPhishingWarning () { console.log('MetaMask - redirecting to phishing warning') window.location.href = 'https://metamask.io/phishing.html' diff --git a/app/scripts/edge-encryptor.js b/app/scripts/edge-encryptor.js index 24c0c93a8..5f6699746 100644 --- a/app/scripts/edge-encryptor.js +++ b/app/scripts/edge-encryptor.js @@ -1,69 +1,97 @@ const asmcrypto = require('asmcrypto.js') const Unibabel = require('browserify-unibabel') +/** + * A Microsoft Edge-specific encryption class that exposes + * the interface expected by eth-keykeyring-controller + */ class EdgeEncryptor { + /** + * Encrypts an arbitrary JavaScript object to cypher text + * + * @param {string} password Password used to unlock a cryptographic key + * @param {Object} dataObject Data to encrypt + * @returns {Object} Object containing cypher text, generation vectors, and salt + */ + encrypt (password, dataObject) { + var salt = this._generateSalt() + return this._keyFromPassword(password, salt) + .then(function (key) { + var data = JSON.stringify(dataObject) + var dataBuffer = Unibabel.utf8ToBuffer(data) + var vector = global.crypto.getRandomValues(new Uint8Array(16)) + var resultbuffer = asmcrypto.AES_GCM.encrypt(dataBuffer, key, vector) - encrypt (password, dataObject) { + var buffer = new Uint8Array(resultbuffer) + var vectorStr = Unibabel.bufferToBase64(vector) + var vaultStr = Unibabel.bufferToBase64(buffer) + return JSON.stringify({ + data: vaultStr, + iv: vectorStr, + salt: salt, + }) + }) + } - var salt = this._generateSalt() - return this._keyFromPassword(password, salt) - .then(function (key) { + /** + * Decrypts an arbitrary JavaScript object from cypher text + * + * @param {string} password Password used to unlock a cryptographic key + * @param {string} text Cypher text of an encrypted JavaScript object + * @returns {Promise} Promise resolving to copy of decrypted JavaScript object + */ + decrypt (password, text) { + const payload = JSON.parse(text) + const salt = payload.salt + return this._keyFromPassword(password, salt) + .then(function (key) { + const encryptedData = Unibabel.base64ToBuffer(payload.data) + const vector = Unibabel.base64ToBuffer(payload.iv) + return new Promise((resolve, reject) => { + var result + try { + result = asmcrypto.AES_GCM.decrypt(encryptedData, key, vector) + } catch (err) { + return reject(new Error('Incorrect password')) + } + const decryptedData = new Uint8Array(result) + const decryptedStr = Unibabel.bufferToUtf8(decryptedData) + const decryptedObj = JSON.parse(decryptedStr) + resolve(decryptedObj) + }) + }) + } - var data = JSON.stringify(dataObject) - var dataBuffer = Unibabel.utf8ToBuffer(data) - var vector = global.crypto.getRandomValues(new Uint8Array(16)) - var resultbuffer = asmcrypto.AES_GCM.encrypt(dataBuffer, key, vector) + /** + * Retrieves a cryptographic key using a password + * + * @private + * @param {string} password Password used to unlock a cryptographic key + * @param {string} salt Random base-64 data + * @returns {Promise} Promise resolving to a derived key + */ + _keyFromPassword (password, salt) { - var buffer = new Uint8Array(resultbuffer) - var vectorStr = Unibabel.bufferToBase64(vector) - var vaultStr = Unibabel.bufferToBase64(buffer) - return JSON.stringify({ - data: vaultStr, - iv: vectorStr, - salt: salt, - }) - }) - } + var passBuffer = Unibabel.utf8ToBuffer(password) + var saltBuffer = Unibabel.base64ToBuffer(salt) + return new Promise((resolve) => { + var key = asmcrypto.PBKDF2_HMAC_SHA256.bytes(passBuffer, saltBuffer, 10000) + resolve(key) + }) + } - decrypt (password, text) { - - const payload = JSON.parse(text) - const salt = payload.salt - return this._keyFromPassword(password, salt) - .then(function (key) { - const encryptedData = Unibabel.base64ToBuffer(payload.data) - const vector = Unibabel.base64ToBuffer(payload.iv) - return new Promise((resolve, reject) => { - var result - try { - result = asmcrypto.AES_GCM.decrypt(encryptedData, key, vector) - } catch (err) { - return reject(new Error('Incorrect password')) - } - const decryptedData = new Uint8Array(result) - const decryptedStr = Unibabel.bufferToUtf8(decryptedData) - const decryptedObj = JSON.parse(decryptedStr) - resolve(decryptedObj) - }) - }) - } - - _keyFromPassword (password, salt) { - - var passBuffer = Unibabel.utf8ToBuffer(password) - var saltBuffer = Unibabel.base64ToBuffer(salt) - return new Promise((resolve) => { - var key = asmcrypto.PBKDF2_HMAC_SHA256.bytes(passBuffer, saltBuffer, 10000) - resolve(key) - }) - } - - _generateSalt (byteCount = 32) { - var view = new Uint8Array(byteCount) - global.crypto.getRandomValues(view) - var b64encoded = btoa(String.fromCharCode.apply(null, view)) - return b64encoded - } + /** + * Generates random base-64 encoded data + * + * @private + * @returns {string} Randomized base-64 encoded data + */ + _generateSalt (byteCount = 32) { + var view = new Uint8Array(byteCount) + global.crypto.getRandomValues(view) + var b64encoded = btoa(String.fromCharCode.apply(null, view)) + return b64encoded + } } module.exports = EdgeEncryptor diff --git a/app/scripts/first-time-state.js b/app/scripts/first-time-state.js index 3063df627..0c8f35303 100644 --- a/app/scripts/first-time-state.js +++ b/app/scripts/first-time-state.js @@ -2,10 +2,16 @@ const env = process.env.METAMASK_ENV const METAMASK_DEBUG = process.env.METAMASK_DEBUG -// -// The default state of MetaMask -// -module.exports = { +/** + * @typedef {Object} FirstTimeState + * @property {Object} config Initial configuration parameters + * @property {Object} NetworkController Network controller state + */ + +/** + * @type {FirstTimeState} The default state of MetaMask + */ +const initialState = { config: {}, NetworkController: { provider: { @@ -13,3 +19,5 @@ module.exports = { }, }, } + +module.exports = initialState diff --git a/app/scripts/inpage.js b/app/scripts/inpage.js index 92c732813..798af78bf 100644 --- a/app/scripts/inpage.js +++ b/app/scripts/inpage.js @@ -42,20 +42,18 @@ log.debug('MetaMask - injected web3') setupDappAutoReload(web3, inpageProvider.publicConfigStore) // set web3 defaultAccount - inpageProvider.publicConfigStore.subscribe(function (state) { web3.eth.defaultAccount = state.selectedAddress }) -// -// util -// - // need to make sure we aren't affected by overlapping namespaces // and that we dont affect the app with our namespace // mostly a fix for web3's BigNumber if AMD's "define" is defined... var __define +/** + * Caches reference to global define object and deletes it + */ function cleanContextForImports () { __define = global.define try { @@ -65,6 +63,9 @@ function cleanContextForImports () { } } +/** + * Restores global define object from cached reference + */ function restoreContextAfterImports () { try { global.define = __define diff --git a/app/scripts/popup-core.js b/app/scripts/popup-core.js index 2e4334bb1..5a5fa95f9 100644 --- a/app/scripts/popup-core.js +++ b/app/scripts/popup-core.js @@ -7,10 +7,14 @@ const launchMetamaskUi = require('../../ui') const StreamProvider = require('web3-stream-provider') const setupMultiplex = require('./lib/stream-utils.js').setupMultiplex - module.exports = initializePopup - +/** + * Asynchronously initializes the MetaMask popup UI + * + * @param {{ container: Element, connectionStream: any }} config Popup configuration object + * @param {Function} cb Called when initialization is comlete + */ function initializePopup ({ container, connectionStream }, cb) { // setup app async.waterfall([ @@ -19,6 +23,12 @@ function initializePopup ({ container, connectionStream }, cb) { ], cb) } +/** + * Establishes streamed connections to background scripts and a Web3 provider + * + * @param {any} connectionStream PortStream instance establishing a background connection + * @param {Function} cb Called when controller connection is established + */ function connectToAccountManager (connectionStream, cb) { // setup communication with background // setup multiplexing @@ -28,6 +38,11 @@ function connectToAccountManager (connectionStream, cb) { setupWeb3Connection(mx.createStream('provider')) } +/** + * Establishes a streamed connection to a Web3 provider + * + * @param {any} connectionStream PortStream instance establishing a background connection + */ function setupWeb3Connection (connectionStream) { var providerStream = new StreamProvider() providerStream.pipe(connectionStream).pipe(providerStream) @@ -38,6 +53,12 @@ function setupWeb3Connection (connectionStream) { global.eth = new Eth(providerStream) } +/** + * Establishes a streamed connection to the background account manager + * + * @param {any} connectionStream PortStream instance establishing a background connection + * @param {Function} cb Called when the remote account manager connection is established + */ function setupControllerConnection (connectionStream, cb) { // this is a really sneaky way of adding EventEmitter api // to a bi-directional dnode instance -- cgit From 6dbdc87713a652dec4c90fa792dda08d613d4198 Mon Sep 17 00:00:00 2001 From: bitpshr Date: Wed, 18 Apr 2018 17:24:36 -0400 Subject: Add generated docs --- app/scripts/config.js | 4 ++-- app/scripts/controllers/token-rates.js | 6 +++--- app/scripts/first-time-state.js | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) (limited to 'app/scripts') diff --git a/app/scripts/config.js b/app/scripts/config.js index 634d7a013..21905d5b4 100644 --- a/app/scripts/config.js +++ b/app/scripts/config.js @@ -47,7 +47,7 @@ global.METAMASK_DEBUG = process.env.METAMASK_DEBUG */ /** - * @type {Config} Application configuration object + * @type {Config} **/ const config = { network: { @@ -76,4 +76,4 @@ const config = { }, } -module.exports = config \ No newline at end of file +module.exports = config diff --git a/app/scripts/controllers/token-rates.js b/app/scripts/controllers/token-rates.js index 22e3e8154..28409ea10 100644 --- a/app/scripts/controllers/token-rates.js +++ b/app/scripts/controllers/token-rates.js @@ -46,7 +46,7 @@ class TokenRatesController { } /** - * @type {Number} - Interval used to poll for exchange rates + * @type {Number} */ set interval (interval) { this._handle && clearInterval(this._handle) @@ -55,7 +55,7 @@ class TokenRatesController { } /** - * @type {Object} - Preferences controller instance + * @type {Object} */ set preferences (preferences) { this._preferences && this._preferences.unsubscribe() @@ -66,7 +66,7 @@ class TokenRatesController { } /** - * @type {Array} - Array of token objects with contract addresses + * @type {Array} */ set tokens (tokens) { this._tokens = tokens diff --git a/app/scripts/first-time-state.js b/app/scripts/first-time-state.js index 0c8f35303..144534f43 100644 --- a/app/scripts/first-time-state.js +++ b/app/scripts/first-time-state.js @@ -9,7 +9,7 @@ const METAMASK_DEBUG = process.env.METAMASK_DEBUG */ /** - * @type {FirstTimeState} The default state of MetaMask + * @type {FirstTimeState} */ const initialState = { config: {}, -- cgit From 1ef6528921263fb9dbae35476a1d9827e1d87508 Mon Sep 17 00:00:00 2001 From: bitpshr Date: Wed, 18 Apr 2018 21:30:13 -0400 Subject: Add JSDoc to various background scripts --- app/scripts/edge-encryptor.js | 12 ++++++------ app/scripts/inpage.js | 4 +++- app/scripts/popup-core.js | 8 ++++---- 3 files changed, 13 insertions(+), 11 deletions(-) (limited to 'app/scripts') diff --git a/app/scripts/edge-encryptor.js b/app/scripts/edge-encryptor.js index 5f6699746..d2e985790 100644 --- a/app/scripts/edge-encryptor.js +++ b/app/scripts/edge-encryptor.js @@ -7,11 +7,11 @@ const Unibabel = require('browserify-unibabel') */ class EdgeEncryptor { /** - * Encrypts an arbitrary JavaScript object to cypher text + * Encrypts an arbitrary JavaScript object to ciphertext * - * @param {string} password Password used to unlock a cryptographic key + * @param {string} password Used to generate a key to encrypt the data * @param {Object} dataObject Data to encrypt - * @returns {Object} Object containing cypher text, generation vectors, and salt + * @returns {Promise} Promise resolving to an object with ciphertext */ encrypt (password, dataObject) { var salt = this._generateSalt() @@ -34,10 +34,10 @@ class EdgeEncryptor { } /** - * Decrypts an arbitrary JavaScript object from cypher text + * Decrypts an arbitrary JavaScript object from ciphertext * - * @param {string} password Password used to unlock a cryptographic key - * @param {string} text Cypher text of an encrypted JavaScript object + * @param {string} password Used to generate a key to decrypt the data + * @param {string} text Ciphertext of an encrypted JavaScript object * @returns {Promise} Promise resolving to copy of decrypted JavaScript object */ decrypt (password, text) { diff --git a/app/scripts/inpage.js b/app/scripts/inpage.js index 798af78bf..6d16eebd4 100644 --- a/app/scripts/inpage.js +++ b/app/scripts/inpage.js @@ -52,7 +52,9 @@ inpageProvider.publicConfigStore.subscribe(function (state) { var __define /** - * Caches reference to global define object and deletes it + * Caches reference to global define object and deletes it to + * avoid conflicts with other global define objects, such as + * AMD's define function */ function cleanContextForImports () { __define = global.define diff --git a/app/scripts/popup-core.js b/app/scripts/popup-core.js index 5a5fa95f9..69fbcf49c 100644 --- a/app/scripts/popup-core.js +++ b/app/scripts/popup-core.js @@ -12,7 +12,7 @@ module.exports = initializePopup /** * Asynchronously initializes the MetaMask popup UI * - * @param {{ container: Element, connectionStream: any }} config Popup configuration object + * @param {{ container: Element, connectionStream: * }} config Popup configuration object * @param {Function} cb Called when initialization is comlete */ function initializePopup ({ container, connectionStream }, cb) { @@ -26,7 +26,7 @@ function initializePopup ({ container, connectionStream }, cb) { /** * Establishes streamed connections to background scripts and a Web3 provider * - * @param {any} connectionStream PortStream instance establishing a background connection + * @param {*} connectionStream PortStream instance establishing a background connection * @param {Function} cb Called when controller connection is established */ function connectToAccountManager (connectionStream, cb) { @@ -41,7 +41,7 @@ function connectToAccountManager (connectionStream, cb) { /** * Establishes a streamed connection to a Web3 provider * - * @param {any} connectionStream PortStream instance establishing a background connection + * @param {*} connectionStream PortStream instance establishing a background connection */ function setupWeb3Connection (connectionStream) { var providerStream = new StreamProvider() @@ -56,7 +56,7 @@ function setupWeb3Connection (connectionStream) { /** * Establishes a streamed connection to the background account manager * - * @param {any} connectionStream PortStream instance establishing a background connection + * @param {*} connectionStream PortStream instance establishing a background connection * @param {Function} cb Called when the remote account manager connection is established */ function setupControllerConnection (connectionStream, cb) { -- cgit From 9c7eafc86f1d9d06dd6a5b66ecd2154b09299d03 Mon Sep 17 00:00:00 2001 From: bitpshr Date: Thu, 19 Apr 2018 14:37:08 -0400 Subject: Add more documentation to computed balances controller --- app/scripts/controllers/computed-balances.js | 37 +++++++++++++++++++++++++++- app/scripts/lib/createProviderMiddleware.js | 6 ++++- app/scripts/lib/port-stream.js | 37 +++++++++++++++++++++++++--- app/scripts/lib/setupMetamaskMeshMetrics.js | 3 +++ 4 files changed, 77 insertions(+), 6 deletions(-) (limited to 'app/scripts') diff --git a/app/scripts/controllers/computed-balances.js b/app/scripts/controllers/computed-balances.js index 907b087cf..cf2e05333 100644 --- a/app/scripts/controllers/computed-balances.js +++ b/app/scripts/controllers/computed-balances.js @@ -2,8 +2,16 @@ const ObservableStore = require('obs-store') const extend = require('xtend') const BalanceController = require('./balance') +/** + * Background controller responsible for syncing + * and computing ETH balances for all accounts + */ class ComputedbalancesController { - + /** + * Creates a new controller instance + * + * @param {Object} [opts] Controller configuration parameters + */ constructor (opts = {}) { const { accountTracker, txController, blockTracker } = opts this.accountTracker = accountTracker @@ -19,6 +27,9 @@ class ComputedbalancesController { this._initBalanceUpdating() } + /** + * Updates balances associated with each internal address + */ updateAllBalances () { Object.keys(this.balances).forEach((balance) => { const address = balance.address @@ -26,12 +37,23 @@ class ComputedbalancesController { }) } + /** + * Initializes internal address tracking + * + * @private + */ _initBalanceUpdating () { const store = this.accountTracker.store.getState() this.syncAllAccountsFromStore(store) this.accountTracker.store.subscribe(this.syncAllAccountsFromStore.bind(this)) } + /** + * Uses current account state to sync and track all + * addresses associated with the current account + * + * @param {Object} store Account tracking state + */ syncAllAccountsFromStore (store) { const upstream = Object.keys(store.accounts) const balances = Object.keys(this.balances) @@ -50,6 +72,13 @@ class ComputedbalancesController { }) } + /** + * Conditionally establishes a new subscription + * to track an address associated with the current + * account + * + * @param {string} address Address to conditionally subscribe to + */ trackAddressIfNotAlready (address) { const state = this.store.getState() if (!(address in state.computedBalances)) { @@ -57,6 +86,12 @@ class ComputedbalancesController { } } + /** + * Establishes a new subscription to track an + * address associated with the current account + * + * @param {string} address Address to conditionally subscribe to + */ trackAddress (address) { const updater = new BalanceController({ address, diff --git a/app/scripts/lib/createProviderMiddleware.js b/app/scripts/lib/createProviderMiddleware.js index 4e667bac2..8a939ba4e 100644 --- a/app/scripts/lib/createProviderMiddleware.js +++ b/app/scripts/lib/createProviderMiddleware.js @@ -1,6 +1,10 @@ module.exports = createProviderMiddleware -// forward requests to provider +/** + * Forwards an HTTP request to the current Web3 provider + * + * @param {{ provider: Object }} config Configuration containing current Web3 provider + */ function createProviderMiddleware ({ provider }) { return (req, res, next, end) => { provider.sendAsync(req, (err, _res) => { diff --git a/app/scripts/lib/port-stream.js b/app/scripts/lib/port-stream.js index a9716fb00..260530e63 100644 --- a/app/scripts/lib/port-stream.js +++ b/app/scripts/lib/port-stream.js @@ -6,6 +6,13 @@ module.exports = PortDuplexStream inherits(PortDuplexStream, Duplex) +/** + * Creates a stream that's both readable and writable. + * The stream supports arbitrary JavaScript objects. + * + * @class + * @param {Object} port Remote Port object + */ function PortDuplexStream (port) { Duplex.call(this, { objectMode: true, @@ -15,8 +22,13 @@ function PortDuplexStream (port) { port.onDisconnect.addListener(this._onDisconnect.bind(this)) } -// private - +/** + * Callback triggered when a message is received from + * the remote Port associated with this Stream. + * + * @private + * @param {Object} msg - Payload from the onMessage listener of Port + */ PortDuplexStream.prototype._onMessage = function (msg) { if (Buffer.isBuffer(msg)) { delete msg._isBuffer @@ -27,14 +39,31 @@ PortDuplexStream.prototype._onMessage = function (msg) { } } +/** + * Callback triggered when the remote Port + * associated with this Stream disconnects. + * + * @private + */ PortDuplexStream.prototype._onDisconnect = function () { this.destroy() } -// stream plumbing - +/** + * Explicitly sets read operations to a no-op + */ PortDuplexStream.prototype._read = noop + +/** + * Called internally when data should be written to + * this writable stream. + * + * @private + * @param {*} msg Arbitrary JavaScript object to write + * @param {string} encoding Encoding to use when writing payload + * @param {Function} cb Called when writing is complete or an error occurs + */ PortDuplexStream.prototype._write = function (msg, encoding, cb) { try { if (Buffer.isBuffer(msg)) { diff --git a/app/scripts/lib/setupMetamaskMeshMetrics.js b/app/scripts/lib/setupMetamaskMeshMetrics.js index 40343f017..79b9cb249 100644 --- a/app/scripts/lib/setupMetamaskMeshMetrics.js +++ b/app/scripts/lib/setupMetamaskMeshMetrics.js @@ -1,6 +1,9 @@ module.exports = setupMetamaskMeshMetrics +/** + * Injects an iframe into the curerent document for testing + */ function setupMetamaskMeshMetrics() { const testingContainer = document.createElement('iframe') testingContainer.src = 'https://metamask.github.io/mesh-testing/' -- cgit From 8636f3bae547ace7d099a3ed516bf013dfe3858e Mon Sep 17 00:00:00 2001 From: bitpshr Date: Thu, 19 Apr 2018 15:12:04 -0400 Subject: Clean up JSDoc for background scripts --- app/scripts/config.js | 4 ++-- app/scripts/contentscript.js | 10 +++++----- app/scripts/controllers/computed-balances.js | 12 ++++++++++-- app/scripts/edge-encryptor.js | 16 ++++++++-------- app/scripts/lib/port-stream.js | 4 ++-- app/scripts/lib/setupMetamaskMeshMetrics.js | 2 +- app/scripts/popup-core.js | 8 ++++---- 7 files changed, 32 insertions(+), 24 deletions(-) (limited to 'app/scripts') diff --git a/app/scripts/config.js b/app/scripts/config.js index 21905d5b4..e6f70ca2b 100644 --- a/app/scripts/config.js +++ b/app/scripts/config.js @@ -34,8 +34,8 @@ global.METAMASK_DEBUG = process.env.METAMASK_DEBUG /** * @typedef {Object} EnumConfig * @property {string} DEFAULT_RPC Default network provider URL - * @property {string} OLD_UI_NETWORK_TYPE - * @property {string} BETA_UI_NETWORK_TYPE + * @property {string} OLD_UI_NETWORK_TYPE Network associated with old UI + * @property {string} BETA_UI_NETWORK_TYPE Network associated with new UI */ /** diff --git a/app/scripts/contentscript.js b/app/scripts/contentscript.js index 728aab8cb..dbf1c6d4c 100644 --- a/app/scripts/contentscript.js +++ b/app/scripts/contentscript.js @@ -112,7 +112,7 @@ function logStreamDisconnectWarning (remoteLabel, err) { /** * Determines if Web3 should be injected * - * @returns {boolean} True of Web3 should be injected + * @returns {boolean} {@code true} if Web3 should be injected */ function shouldInjectWeb3 () { return doctypeCheck() && suffixCheck() @@ -122,7 +122,7 @@ function shouldInjectWeb3 () { /** * Checks the doctype of the current document if it exists * - * @returns {boolean} True if the doctype is html or if none exists + * @returns {boolean} {@code true} if the doctype is html or if none exists */ function doctypeCheck () { const doctype = window.document.doctype @@ -136,7 +136,7 @@ function doctypeCheck () { /** * Checks the current document extension * - * @returns {boolean} True if the current extension is not prohibited + * @returns {boolean} {@code true} if the current extension is not prohibited */ function suffixCheck () { var prohibitedTypes = ['xml', 'pdf'] @@ -154,7 +154,7 @@ function suffixCheck () { /** * Checks the documentElement of the current document * - * @returns {boolean} True if the documentElement is an html node or if none exists + * @returns {boolean} {@code true} if the documentElement is an html node or if none exists */ function documentElementCheck () { var documentElement = document.documentElement.nodeName @@ -167,7 +167,7 @@ function documentElementCheck () { /** * Checks if the current domain is blacklisted * - * @returns {boolean} True if the current domain is blacklisted + * @returns {boolean} {@code true} if the current domain is blacklisted */ function blacklistedDomainCheck () { var blacklistedDomains = [ diff --git a/app/scripts/controllers/computed-balances.js b/app/scripts/controllers/computed-balances.js index cf2e05333..1a6802f9a 100644 --- a/app/scripts/controllers/computed-balances.js +++ b/app/scripts/controllers/computed-balances.js @@ -2,6 +2,14 @@ const ObservableStore = require('obs-store') const extend = require('xtend') const BalanceController = require('./balance') +/** + * @typedef {Object} ComputedBalancesOptions + * @property {Object} accountTracker Account tracker store reference + * @property {Object} txController Token controller reference + * @property {Object} blockTracker Block tracker reference + * @property {Object} initState Initial state to populate this internal store with + */ + /** * Background controller responsible for syncing * and computing ETH balances for all accounts @@ -10,7 +18,7 @@ class ComputedbalancesController { /** * Creates a new controller instance * - * @param {Object} [opts] Controller configuration parameters + * @param {ComputedBalancesOptions} [opts] Controller configuration parameters */ constructor (opts = {}) { const { accountTracker, txController, blockTracker } = opts @@ -52,7 +60,7 @@ class ComputedbalancesController { * Uses current account state to sync and track all * addresses associated with the current account * - * @param {Object} store Account tracking state + * @param {{ accounts: Object }} store Account tracking state */ syncAllAccountsFromStore (store) { const upstream = Object.keys(store.accounts) diff --git a/app/scripts/edge-encryptor.js b/app/scripts/edge-encryptor.js index d2e985790..dcb06873b 100644 --- a/app/scripts/edge-encryptor.js +++ b/app/scripts/edge-encryptor.js @@ -7,11 +7,11 @@ const Unibabel = require('browserify-unibabel') */ class EdgeEncryptor { /** - * Encrypts an arbitrary JavaScript object to ciphertext + * Encrypts an arbitrary object to ciphertext * * @param {string} password Used to generate a key to encrypt the data * @param {Object} dataObject Data to encrypt - * @returns {Promise} Promise resolving to an object with ciphertext + * @returns {Promise} Promise resolving to an object with ciphertext */ encrypt (password, dataObject) { var salt = this._generateSalt() @@ -34,11 +34,11 @@ class EdgeEncryptor { } /** - * Decrypts an arbitrary JavaScript object from ciphertext + * Decrypts an arbitrary object from ciphertext * * @param {string} password Used to generate a key to decrypt the data - * @param {string} text Ciphertext of an encrypted JavaScript object - * @returns {Promise} Promise resolving to copy of decrypted JavaScript object + * @param {string} text Ciphertext of an encrypted object + * @returns {Promise} Promise resolving to copy of decrypted object */ decrypt (password, text) { const payload = JSON.parse(text) @@ -67,7 +67,7 @@ class EdgeEncryptor { * * @private * @param {string} password Password used to unlock a cryptographic key - * @param {string} salt Random base-64 data + * @param {string} salt Random base64 data * @returns {Promise} Promise resolving to a derived key */ _keyFromPassword (password, salt) { @@ -81,10 +81,10 @@ class EdgeEncryptor { } /** - * Generates random base-64 encoded data + * Generates random base64 encoded data * * @private - * @returns {string} Randomized base-64 encoded data + * @returns {string} Randomized base64 encoded data */ _generateSalt (byteCount = 32) { var view = new Uint8Array(byteCount) diff --git a/app/scripts/lib/port-stream.js b/app/scripts/lib/port-stream.js index 260530e63..5c4224fd9 100644 --- a/app/scripts/lib/port-stream.js +++ b/app/scripts/lib/port-stream.js @@ -8,7 +8,7 @@ inherits(PortDuplexStream, Duplex) /** * Creates a stream that's both readable and writable. - * The stream supports arbitrary JavaScript objects. + * The stream supports arbitrary objects. * * @class * @param {Object} port Remote Port object @@ -60,7 +60,7 @@ PortDuplexStream.prototype._read = noop * this writable stream. * * @private - * @param {*} msg Arbitrary JavaScript object to write + * @param {*} msg Arbitrary object to write * @param {string} encoding Encoding to use when writing payload * @param {Function} cb Called when writing is complete or an error occurs */ diff --git a/app/scripts/lib/setupMetamaskMeshMetrics.js b/app/scripts/lib/setupMetamaskMeshMetrics.js index 79b9cb249..02690a948 100644 --- a/app/scripts/lib/setupMetamaskMeshMetrics.js +++ b/app/scripts/lib/setupMetamaskMeshMetrics.js @@ -2,7 +2,7 @@ module.exports = setupMetamaskMeshMetrics /** - * Injects an iframe into the curerent document for testing + * Injects an iframe into the current document for testing */ function setupMetamaskMeshMetrics() { const testingContainer = document.createElement('iframe') diff --git a/app/scripts/popup-core.js b/app/scripts/popup-core.js index 69fbcf49c..6325b8a8d 100644 --- a/app/scripts/popup-core.js +++ b/app/scripts/popup-core.js @@ -13,7 +13,7 @@ module.exports = initializePopup * Asynchronously initializes the MetaMask popup UI * * @param {{ container: Element, connectionStream: * }} config Popup configuration object - * @param {Function} cb Called when initialization is comlete + * @param {Function} cb Called when initialization is complete */ function initializePopup ({ container, connectionStream }, cb) { // setup app @@ -26,7 +26,7 @@ function initializePopup ({ container, connectionStream }, cb) { /** * Establishes streamed connections to background scripts and a Web3 provider * - * @param {*} connectionStream PortStream instance establishing a background connection + * @param {PortDuplexStream} connectionStream PortStream instance establishing a background connection * @param {Function} cb Called when controller connection is established */ function connectToAccountManager (connectionStream, cb) { @@ -41,7 +41,7 @@ function connectToAccountManager (connectionStream, cb) { /** * Establishes a streamed connection to a Web3 provider * - * @param {*} connectionStream PortStream instance establishing a background connection + * @param {PortDuplexStream} connectionStream PortStream instance establishing a background connection */ function setupWeb3Connection (connectionStream) { var providerStream = new StreamProvider() @@ -56,7 +56,7 @@ function setupWeb3Connection (connectionStream) { /** * Establishes a streamed connection to the background account manager * - * @param {*} connectionStream PortStream instance establishing a background connection + * @param {PortDuplexStream} connectionStream PortStream instance establishing a background connection * @param {Function} cb Called when the remote account manager connection is established */ function setupControllerConnection (connectionStream, cb) { -- cgit