Merge pull request #240 from LiskHQ/30-add-documentation

Add documentation, Fixes #30
LiskArchive · May 18, 2017 · e1f9d62 · e1f9d62
2 parents ec07b7a + 4c62cf7
commit e1f9d62
Show file tree

Hide file tree

Showing 35 changed files with 917 additions and 66 deletions.
diff --git a/package.json b/package.json
@@ -27,6 +27,5 @@
     "win": {
       "target": "nsis"
     }
-  },
-  "license": "GPL-3.0"
+  }
 }
diff --git a/src/app/app.js b/src/app/app.js
@@ -1,3 +1,10 @@
+/**
+ * The main application
+ * This is an Angular module to nest all the other sub-modules
+ * and also to apply routing.
+ *
+ * @namespace app
+ */
 const app = angular.module('app', [
   'ui.router',
   'angular-svg-round-progressbar',

diff --git a/src/app/components/delegate-registration/delegateRegistration.js b/src/app/components/delegate-registration/delegateRegistration.js
@@ -1,5 +1,11 @@
 import './delegateRegistration.less';
 
+/**
+ * @description The directive performing as the form to register the account as delegate
+ *
+ * @class app.delegateRegistration
+ * @memberOf app
+ */
 app.directive('delegateRegistration', ($mdDialog, delegateService, Account, dialog, $rootScope) => {
   const DelegateRegistrationLink = function ($scope, $element) {
     function checkPendingRegistration() {
@@ -46,6 +52,12 @@ app.directive('delegateRegistration', ($mdDialog, delegateService, Account, dial
       },
     };
 
+    /**
+     * Resets the from fields and form state.
+     *
+     * @method reset
+     * @param {Object} from - The form event object. containing form elements and errors list.
+     */
     $scope.reset = (form) => {
       $scope.form.name = '';
       $scope.form.error = '';
@@ -54,11 +66,22 @@ app.directive('delegateRegistration', ($mdDialog, delegateService, Account, dial
       form.$setUntouched();
     };
 
+    /**
+     * hides the dialog and resets form.
+     *
+     * @method cancel
+     * @param {Object} from - The form event object. containing form elements and errors list.
+     */
     $scope.cancel = (form) => {
       $scope.reset(form);
       $mdDialog.hide();
     };
 
+    /**
+     * Shows from dialog.
+     *
+     * @todo This should be replaced by a general dialog directive.
+     */
     $element.bind('click', () => {
       $mdDialog.show({
         template: require('./delegateRegistration.pug')(),

diff --git a/src/app/components/delegates/delegates.js b/src/app/components/delegates/delegates.js
@@ -2,12 +2,24 @@ import './delegates.less';
 
 const UPDATE_INTERVAL = 10000;
 
+/**
+ * The delegates tab component
+ *
+ * @module app
+ * @submodule delegates
+ */
 app.component('delegates', {
   template: require('./delegates.pug')(),
   bindings: {
     account: '=',
     passphrase: '<',
   },
+  /**
+   * The delegates tab component constructor class
+   *
+   * @class delegates
+   * @constructor
+   */
   controller: class delegates {
     constructor($scope, $rootScope, Peers, $mdDialog, $mdMedia,
       dialog, $timeout, delegateService, Account) {
@@ -44,6 +56,11 @@ app.component('delegates', {
       });
     }
 
+    /**
+     * Updates the lists of delegates and voted delegates
+     *
+     * @method updateAll
+     */
     updateAll() {
       this.delegates = [];
       this.delegatesDisplayedCount = 20;
@@ -60,24 +77,45 @@ app.component('delegates', {
       }
     }
 
-    loadDelegates(offset, search, replace) {
+    /**
+     * Fetches a list of delegates based on the given search phrase
+     *
+     * @method loadDelegates
+     * @param {Number} offset - The starting index of for the results
+     * @param {String} search - The search phrase to match with the delegate name
+     * @param {Boolean} replace - Passed to addDelegates, defines if the results
+     *  should replace the old delegates list
+     * @param {Number} limit - The maximum number of results
+     */
+    loadDelegates(offset, search, replace, limit = 100) {
       this.loading = true;
       this.delegateService.listDelegates({
         offset,
-        limit: '100',
+        limit: limit.toString(),
         q: search,
       }).then((data) => {
         this.addDelegates(data, replace);
       });
       this.lastSearch = search;
     }
 
+    /**
+     * Fills the list of delegates, sets their voted and changed status
+     *
+     * @method addDelegates
+     * @param {Object} data - The result of delegateService.listDelegates Api call
+     * @param {Boolean} replace - defines if the results should replace
+     *  the old delegates list
+     */
     addDelegates(data, replace) {
       if (data.success) {
         if (replace) {
-          this.delegates = [];
+          this.delegates = data.delegates;
+        } else {
+          this.delegates = this.delegates.concat(data.delegates);
         }
-        this.delegates = this.delegates.concat(data.delegates.map((delegate) => {
+
+        data.delegates.forEach((delegate) => {
           const voted = this.votedDict[delegate.username] !== undefined;
           const changed = this.voteList.concat(this.unvoteList)
             .map(d => d.username).indexOf(delegate.username) !== -1;
@@ -86,13 +124,18 @@ app.component('delegates', {
             voted,
             changed,
           };
-          return delegate;
-        }));
+        });
+
         this.delegatesTotalCount = data.totalCount;
         this.loading = false;
       }
     }
 
+    /**
+     * Needs summary
+     *
+     * @method showMore
+     */
     showMore() {
       if (this.delegatesDisplayedCount < this.delegates.length) {
         this.delegatesDisplayedCount += 20;
@@ -104,6 +147,12 @@ app.component('delegates', {
       }
     }
 
+    /**
+     * Needs summary
+     *
+     * @method selectionChange
+     * @param {any} delegate
+     */
     selectionChange(delegate) {
       // eslint-disable-next-line no-param-reassign
       delegate.status.changed = delegate.status.voted !== delegate.status.selected;
@@ -115,10 +164,21 @@ app.component('delegates', {
       }
     }
 
+    /**
+     * Needs summary
+     *
+     * @method clearSearch
+     */
     clearSearch() {
       this.$scope.search = '';
     }
 
+    /**
+     * Adds delegates to vote delegates list
+     *
+     * @method addToUnvoteList
+     * @param {Object} vote - The delegate to add to voted delegates list
+     */
     addToUnvoteList(vote) {
       const delegate = this.delegates.filter(d => d.username === vote.username)[0] || vote;
       if (delegate.status.selected) {
@@ -127,6 +187,11 @@ app.component('delegates', {
       delegate.status.selected = false;
     }
 
+    /**
+     * Needs summary
+     *
+     * @method setPendingVotes
+     */
     setPendingVotes() {
       this.voteList.forEach((delegate) => {
         /* eslint-disable no-param-reassign */
@@ -146,6 +211,13 @@ app.component('delegates', {
       this.checkPendingVotes();
     }
 
+    /**
+     * Fetches the list of delegates we've voted for (voted delegates),
+     * and updates the list and removes the confirmed votes from votePendingList
+     *
+     * @method checkPendingVotes
+     * @todo Use Sync service and remove recursive timeout
+     */
     checkPendingVotes() {
       this.$timeout(() => {
         this.delegateService.listAccountDelegates(this.account.get().address,
@@ -178,14 +250,27 @@ app.component('delegates', {
       }, UPDATE_INTERVAL);
     }
 
+    /**
+     * Needs summary
+     *
+     * @method parseVoteListFromInput
+     */
     parseVoteListFromInput() {
       this._parseListFromInput('voteList');
     }
 
+    /**
+     * Needs summary
+     *
+     * @method parseUnvoteListFromInput
+     */
     parseUnvoteListFromInput() {
       this._parseListFromInput('unvoteList');
     }
 
+    /**
+     * @private
+     */
     _parseListFromInput(listName) {
       const list = this[listName];
       this.invalidUsernames = [];
@@ -203,6 +288,9 @@ app.component('delegates', {
       }
     }
 
+    /**
+     * @private
+     */
     _selectFinish(success, list) {
       if (list.length !== 0) {
         this.usernameListActive = false;
@@ -213,6 +301,9 @@ app.component('delegates', {
       }
     }
 
+    /**
+     * @private
+     */
     _setSelected(username, list) {
       const delegate = this.delegates.filter(d => d.username === username)[0];
       if (delegate) {
@@ -232,7 +323,6 @@ app.component('delegates', {
         });
       }
     }
-
     // eslint-disable-next-line class-methods-use-this
     _selectDelegate(delegate, list) {
       // eslint-disable-next-line no-param-reassign
@@ -244,6 +334,12 @@ app.component('delegates', {
       }
     }
 
+    /**
+     * Uses mdDialog to show vote list directive.
+     *
+     * @method openVoteDialog
+     * @todo Use a general dialog service instead.
+     */
     openVoteDialog() {
       this.$mdDialog.show({
         controllerAs: '$ctrl',