From 20a075657f9c8133b65ea9cf6e8f1f633bc8a8e6 Mon Sep 17 00:00:00 2001 From: Dan Date: Mon, 16 Apr 2018 14:38:04 -0230 Subject: Documentation for various controllers and libs --- app/scripts/controllers/preferences.js | 124 +++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) (limited to 'app/scripts/controllers/preferences.js') diff --git a/app/scripts/controllers/preferences.js b/app/scripts/controllers/preferences.js index b4819d951..92c016309 100644 --- a/app/scripts/controllers/preferences.js +++ b/app/scripts/controllers/preferences.js @@ -4,6 +4,21 @@ const extend = require('xtend') class PreferencesController { + /** + * + * @typedef {Object} PreferencesController + * @param {object} opts Overides the defaults for the initial state of this.store + * @property {object} store The an object containing a users preferences, stored in local storage + * @property {array} store.frequentRpcList A list of custom rpcs to provide the user + * @property {string} store.currentAccountTab Indicates the selected tab in the ui + * @property {array} store.tokens The tokens the user wants display in their token lists + * @property {boolean} store.useBlockie The users preference for blockie identicons within the UI + * @property {object} store.featureFlags A key-boolean map, where keys refer to features and booleans to whether the + * user wishes to see that feature + * @property {string} store.currentLocale The preferred language locale key + * @property {string} store.selectedAddress A hex string that matches the currently selected address in the app + * + */ constructor (opts = {}) { const initState = extend({ frequentRpcList: [], @@ -17,18 +32,43 @@ class PreferencesController { } // PUBLIC METHODS + /** + * Setter for the `useBlockie` property + * + * @param {boolean} val Whether or not the user prefers blockie indicators + * + */ setUseBlockie (val) { this.store.updateState({ useBlockie: val }) } + /** + * Getter for the `useBlockie` property + * + * @returns {boolean} this.store.useBlockie + * + */ getUseBlockie () { return this.store.getState().useBlockie } + /** + * Setter for the `currentLocale` property + * + * @param {string} key he preferred language locale key + * + */ setCurrentLocale (key) { this.store.updateState({ currentLocale: key }) } + /** + * Setter for the `selectedAddress` property + * + * @param {string} _address A new hex address for an account + * @returns {Promise} Promises an undefined return value + * + */ setSelectedAddress (_address) { return new Promise((resolve, reject) => { const address = normalizeAddress(_address) @@ -37,10 +77,37 @@ class PreferencesController { }) } + /** + * Getter for the `selectedAddress` property + * + * @returns {string} The hex address for the currently selected account + * + */ getSelectedAddress () { return this.store.getState().selectedAddress } + /** + * Contains data about tokens users add to their account. + * @typedef {Object} AddedToken + * @property {string} address - The hex address for the token contract. Will be all lower cased and hex-prefixed. + * @property {string} symbol - The symbol of the token, usually 3 or 4 capitalized letters + * {@link https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md#symbol} + * @property {boolean} decimals - The number of decimals the token uses. + * {@link https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md#decimals} + */ + + /** + * Adds a new token to the token array, or updates the token if passed an address that already exists. + * Modifies the existing tokens array from the store. All objects in the tokens array array AddedToken objects. + * @see AddedToken {@link AddedToken} + * + * @param {string} rawAddress Hex address of the token contract. May or may not be a checksum address. + * @param {string} symbol The symbol of the token + * @param {number} decimals The number of decimals the token uses. + * @returns {Promise} Promises the new array of AddedToken objects. + * + */ async addToken (rawAddress, symbol, decimals) { const address = normalizeAddress(rawAddress) const newEntry = { address, symbol, decimals } @@ -62,6 +129,13 @@ class PreferencesController { return Promise.resolve(tokens) } + /** + * Removes a specified token from the tokens array. + * + * @param {string} rawAddress Hex address of the token contract to remove. + * @returns {Promise The new array of AddedToken objects + * + */ removeToken (rawAddress) { const tokens = this.store.getState().tokens @@ -71,10 +145,23 @@ class PreferencesController { return Promise.resolve(updatedTokens) } + /** + * A getter for the `tokens` property + * + * @returns {array} The current array of AddedToken objects + * + */ getTokens () { return this.store.getState().tokens } + /** + * Gets an updated rpc list from this.addToFrequentRpcList() and sets the `frequentRpcList` to this update list. + * + * @param {string} _url The the new rpc url to add to the updated list + * @returns {Promise} Promises an undefined value. + * + */ updateFrequentRpcList (_url) { return this.addToFrequentRpcList(_url) .then((rpcList) => { @@ -83,6 +170,13 @@ class PreferencesController { }) } + /** + * Setter for the `currentAccountTab` property + * + * @param {string} currentAccountTab Specifies the new tab to be marked as current + * @returns {Promise} Promises an undefined value. + * + */ setCurrentAccountTab (currentAccountTab) { return new Promise((resolve, reject) => { this.store.updateState({ currentAccountTab }) @@ -90,6 +184,15 @@ class PreferencesController { }) } + /** + * Returns an updated rpcList based on the passed url and the current list. + * The returned list will have a max length of 2. If the _url currently exists it the list, it will be moved to the + * end of the list. The current list is modified and returned as a promise. + * + * @param {string} _url The rpc url to add to the frequentRpcList. + * @returns {Promise} The updated frequentRpcList. + * + */ addToFrequentRpcList (_url) { const rpcList = this.getFrequentRpcList() const index = rpcList.findIndex((element) => { return element === _url }) @@ -105,10 +208,24 @@ class PreferencesController { return Promise.resolve(rpcList) } + /** + * Getter for the `frequentRpcList` property. + * + * @returns {array} An array of one or two rpc urls. + * + */ getFrequentRpcList () { return this.store.getState().frequentRpcList } + /** + * Updates the `featureFlags` property, which is an object. One property within that object will be set to a boolean. + * + * @param {string} feature A key that corresponds to a UI feature. + * @param {boolean} activated Indicates whether or not the UI feature should be displayed + * @returns {Promise} Promises a new object; the updated featureFlags object. + * + */ setFeatureFlag (feature, activated) { const currentFeatureFlags = this.store.getState().featureFlags const updatedFeatureFlags = { @@ -121,6 +238,13 @@ class PreferencesController { return Promise.resolve(updatedFeatureFlags) } + /** + * A getter for the `featureFlags` property + * + * @returns {object} A key-boolean map, where keys refer to features and booleans to whether the + * user wishes to see that feature + * + */ getFeatureFlags () { return this.store.getState().featureFlags } -- cgit v1.2.3 From e9ca7199ab9b63ef728fa93f8e98295c3096c553 Mon Sep 17 00:00:00 2001 From: Dan Date: Mon, 16 Apr 2018 21:23:29 -0230 Subject: Typo fixes, type fixes on the return clauses of the buyEthUrl and getPrefferedLangCode functions. --- app/scripts/controllers/preferences.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'app/scripts/controllers/preferences.js') diff --git a/app/scripts/controllers/preferences.js b/app/scripts/controllers/preferences.js index 92c016309..cf0ca13a8 100644 --- a/app/scripts/controllers/preferences.js +++ b/app/scripts/controllers/preferences.js @@ -7,7 +7,7 @@ class PreferencesController { /** * * @typedef {Object} PreferencesController - * @param {object} opts Overides the defaults for the initial state of this.store + * @param {object} opts Overrides the defaults for the initial state of this.store * @property {object} store The an object containing a users preferences, stored in local storage * @property {array} store.frequentRpcList A list of custom rpcs to provide the user * @property {string} store.currentAccountTab Indicates the selected tab in the ui -- cgit v1.2.3 From 128cb1af46224da9c0f5158107b6ac2da40b0622 Mon Sep 17 00:00:00 2001 From: Dan Date: Tue, 17 Apr 2018 00:54:16 -0230 Subject: Improve documentation of promises that return undefined. --- app/scripts/controllers/preferences.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'app/scripts/controllers/preferences.js') diff --git a/app/scripts/controllers/preferences.js b/app/scripts/controllers/preferences.js index cf0ca13a8..653e6d762 100644 --- a/app/scripts/controllers/preferences.js +++ b/app/scripts/controllers/preferences.js @@ -66,7 +66,7 @@ class PreferencesController { * Setter for the `selectedAddress` property * * @param {string} _address A new hex address for an account - * @returns {Promise} Promises an undefined return value + * @returns {Promise} Promise resolves with undefined * */ setSelectedAddress (_address) { @@ -159,7 +159,7 @@ class PreferencesController { * Gets an updated rpc list from this.addToFrequentRpcList() and sets the `frequentRpcList` to this update list. * * @param {string} _url The the new rpc url to add to the updated list - * @returns {Promise} Promises an undefined value. + * @returns {Promise} Promise resolves with undefined * */ updateFrequentRpcList (_url) { @@ -174,7 +174,7 @@ class PreferencesController { * Setter for the `currentAccountTab` property * * @param {string} currentAccountTab Specifies the new tab to be marked as current - * @returns {Promise} Promises an undefined value. + * @returns {Promise} Promise resolves with undefined * */ setCurrentAccountTab (currentAccountTab) { -- cgit v1.2.3 From e80bd230b9bb6ac9ff05d7095f74dd2fd7ebb3af Mon Sep 17 00:00:00 2001 From: Dan Date: Wed, 18 Apr 2018 16:11:39 -0230 Subject: NO MIXED TABS AND SPACES --- app/scripts/controllers/preferences.js | 162 ++++++++++++++++----------------- 1 file changed, 81 insertions(+), 81 deletions(-) (limited to 'app/scripts/controllers/preferences.js') diff --git a/app/scripts/controllers/preferences.js b/app/scripts/controllers/preferences.js index 653e6d762..29214d072 100644 --- a/app/scripts/controllers/preferences.js +++ b/app/scripts/controllers/preferences.js @@ -4,12 +4,12 @@ const extend = require('xtend') class PreferencesController { - /** - * + /** + * * @typedef {Object} PreferencesController - * @param {object} opts Overrides the defaults for the initial state of this.store + * @param {object} opts Overrides the defaults for the initial state of this.store * @property {object} store The an object containing a users preferences, stored in local storage - * @property {array} store.frequentRpcList A list of custom rpcs to provide the user + * @property {array} store.frequentRpcList A list of custom rpcs to provide the user * @property {string} store.currentAccountTab Indicates the selected tab in the ui * @property {array} store.tokens The tokens the user wants display in their token lists * @property {boolean} store.useBlockie The users preference for blockie identicons within the UI @@ -18,7 +18,7 @@ class PreferencesController { * @property {string} store.currentLocale The preferred language locale key * @property {string} store.selectedAddress A hex string that matches the currently selected address in the app * - */ + */ constructor (opts = {}) { const initState = extend({ frequentRpcList: [], @@ -32,43 +32,43 @@ class PreferencesController { } // PUBLIC METHODS - /** - * Setter for the `useBlockie` property - * - * @param {boolean} val Whether or not the user prefers blockie indicators - * - */ + /** + * Setter for the `useBlockie` property + * + * @param {boolean} val Whether or not the user prefers blockie indicators + * + */ setUseBlockie (val) { this.store.updateState({ useBlockie: val }) } - /** - * Getter for the `useBlockie` property - * - * @returns {boolean} this.store.useBlockie - * - */ + /** + * Getter for the `useBlockie` property + * + * @returns {boolean} this.store.useBlockie + * + */ getUseBlockie () { return this.store.getState().useBlockie } - /** - * Setter for the `currentLocale` property + /** + * Setter for the `currentLocale` property * * @param {string} key he preferred language locale key - * - */ + * + */ setCurrentLocale (key) { this.store.updateState({ currentLocale: key }) } - /** - * Setter for the `selectedAddress` property - * - * @param {string} _address A new hex address for an account - * @returns {Promise} Promise resolves with undefined - * - */ + /** + * Setter for the `selectedAddress` property + * + * @param {string} _address A new hex address for an account + * @returns {Promise} Promise resolves with undefined + * + */ setSelectedAddress (_address) { return new Promise((resolve, reject) => { const address = normalizeAddress(_address) @@ -129,13 +129,13 @@ class PreferencesController { return Promise.resolve(tokens) } - /** - * Removes a specified token from the tokens array. - * - * @param {string} rawAddress Hex address of the token contract to remove. - * @returns {Promise The new array of AddedToken objects - * - */ + /** + * Removes a specified token from the tokens array. + * + * @param {string} rawAddress Hex address of the token contract to remove. + * @returns {Promise The new array of AddedToken objects + * + */ removeToken (rawAddress) { const tokens = this.store.getState().tokens @@ -145,23 +145,23 @@ class PreferencesController { return Promise.resolve(updatedTokens) } - /** - * A getter for the `tokens` property - * - * @returns {array} The current array of AddedToken objects - * - */ + /** + * A getter for the `tokens` property + * + * @returns {array} The current array of AddedToken objects + * + */ getTokens () { return this.store.getState().tokens } - /** - * Gets an updated rpc list from this.addToFrequentRpcList() and sets the `frequentRpcList` to this update list. - * - * @param {string} _url The the new rpc url to add to the updated list - * @returns {Promise} Promise resolves with undefined - * - */ + /** + * Gets an updated rpc list from this.addToFrequentRpcList() and sets the `frequentRpcList` to this update list. + * + * @param {string} _url The the new rpc url to add to the updated list + * @returns {Promise} Promise resolves with undefined + * + */ updateFrequentRpcList (_url) { return this.addToFrequentRpcList(_url) .then((rpcList) => { @@ -170,13 +170,13 @@ class PreferencesController { }) } - /** - * Setter for the `currentAccountTab` property - * - * @param {string} currentAccountTab Specifies the new tab to be marked as current - * @returns {Promise} Promise resolves with undefined - * - */ + /** + * Setter for the `currentAccountTab` property + * + * @param {string} currentAccountTab Specifies the new tab to be marked as current + * @returns {Promise} Promise resolves with undefined + * + */ setCurrentAccountTab (currentAccountTab) { return new Promise((resolve, reject) => { this.store.updateState({ currentAccountTab }) @@ -184,15 +184,15 @@ class PreferencesController { }) } - /** - * Returns an updated rpcList based on the passed url and the current list. + /** + * Returns an updated rpcList based on the passed url and the current list. * The returned list will have a max length of 2. If the _url currently exists it the list, it will be moved to the * end of the list. The current list is modified and returned as a promise. - * - * @param {string} _url The rpc url to add to the frequentRpcList. - * @returns {Promise} The updated frequentRpcList. - * - */ + * + * @param {string} _url The rpc url to add to the frequentRpcList. + * @returns {Promise} The updated frequentRpcList. + * + */ addToFrequentRpcList (_url) { const rpcList = this.getFrequentRpcList() const index = rpcList.findIndex((element) => { return element === _url }) @@ -208,24 +208,24 @@ class PreferencesController { return Promise.resolve(rpcList) } - /** - * Getter for the `frequentRpcList` property. - * - * @returns {array} An array of one or two rpc urls. - * - */ + /** + * Getter for the `frequentRpcList` property. + * + * @returns {array} An array of one or two rpc urls. + * + */ getFrequentRpcList () { return this.store.getState().frequentRpcList } - /** - * Updates the `featureFlags` property, which is an object. One property within that object will be set to a boolean. - * - * @param {string} feature A key that corresponds to a UI feature. + /** + * Updates the `featureFlags` property, which is an object. One property within that object will be set to a boolean. + * + * @param {string} feature A key that corresponds to a UI feature. * @param {boolean} activated Indicates whether or not the UI feature should be displayed - * @returns {Promise} Promises a new object; the updated featureFlags object. - * - */ + * @returns {Promise} Promises a new object; the updated featureFlags object. + * + */ setFeatureFlag (feature, activated) { const currentFeatureFlags = this.store.getState().featureFlags const updatedFeatureFlags = { @@ -238,13 +238,13 @@ class PreferencesController { return Promise.resolve(updatedFeatureFlags) } - /** - * A getter for the `featureFlags` property - * - * @returns {object} A key-boolean map, where keys refer to features and booleans to whether the + /** + * A getter for the `featureFlags` property + * + * @returns {object} A key-boolean map, where keys refer to features and booleans to whether the * user wishes to see that feature - * - */ + * + */ getFeatureFlags () { return this.store.getState().featureFlags } -- cgit v1.2.3 From 164f9c4662072dc0960ee5dc2c021545a7b14d8a Mon Sep 17 00:00:00 2001 From: Dan Date: Wed, 18 Apr 2018 16:17:06 -0230 Subject: Missing bracket in docblock. --- app/scripts/controllers/preferences.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'app/scripts/controllers/preferences.js') diff --git a/app/scripts/controllers/preferences.js b/app/scripts/controllers/preferences.js index 29214d072..d4d508026 100644 --- a/app/scripts/controllers/preferences.js +++ b/app/scripts/controllers/preferences.js @@ -133,7 +133,7 @@ class PreferencesController { * Removes a specified token from the tokens array. * * @param {string} rawAddress Hex address of the token contract to remove. - * @returns {Promise The new array of AddedToken objects + * @returns {Promise} The new array of AddedToken objects * */ removeToken (rawAddress) { -- cgit v1.2.3