Merge pull request #592 from crossroads/master

Release#2 Jan2020

Author: abulsayyad123

.circleci/config.yml

@@ -3,7 +3,7 @@ version: 2
 aliases:
   - defaults: &defaults
       docker:
-        - image: circleci/node:boron
+        - image: circleci/node:8.15
       working_directory: ~/code
   - &restore-repo-cache
     key: v1-stock-goodcity-{{ .Environment.CIRCLE_SHA1 }}
@@ -74,7 +74,7 @@ jobs:
   test_cases:
     <<: *defaults
     docker:
-      - image: circleci/node:6-browsers
+      - image: circleci/node:8.15-browsers
     environment:
       JOBS: 1
     steps:

.gitignore

@@ -3,6 +3,7 @@
 # compiled output
 /dist
 /tmp
+/documentation
 
 .vscode
 .idea

Gemfile.lock

@@ -71,7 +71,7 @@ GEM
     faraday_middleware (0.13.1)
       faraday (>= 0.7.4, < 1.0)
     fastimage (2.1.7)
-    fastlane (2.139.0)
+    fastlane (2.140.0)
       CFPropertyList (>= 2.3, < 4.0.0)
       addressable (>= 2.3, < 3.0.0)
       babosa (>= 1.0.2, < 2.0.0)
@@ -119,10 +119,12 @@ GEM
       representable (~> 3.0)
       retriable (>= 2.0, < 4.0)
       signet (~> 0.12)
-    google-cloud-core (1.4.1)
+    google-cloud-core (1.5.0)
       google-cloud-env (~> 1.0)
+      google-cloud-errors (~> 1.0)
     google-cloud-env (1.3.0)
       faraday (~> 0.11)
+    google-cloud-errors (1.0.0)
     google-cloud-storage (1.25.1)
       addressable (~> 2.5)
       digest-crc (~> 0.4)

README.md

@@ -50,6 +50,16 @@ Make use of the many generators for code, try `ember help generate` for more det
 
 Specify what it takes to deploy your app.
 
+### Documentation
+
+Re-usable mixins/components/services of the project have been documented with JSDoc comments.
+Documentation can be generated using the following commands :
+
+```bash
+$> yarn document # generates a 'documentation' folder
+$> open documentation/index.html # view the documentation in your browser
+```
+
 ## Further Reading / Useful Links
 
 * [ember.js](http://emberjs.com/)

app/components/goodcity/orders-package-block.js

@@ -29,20 +29,22 @@ const CANCELLED = {};
 /**
  * UI Component representing an orders_package
  *
- * --------------------------------------------------------
- * | op_state  |   order_code         order_state |    <  |
- * |           |                                  |  <    |
- * | qty       |   organisation                   |    <  |
- * --------------------------------------------------------
+ *  --------------------------------------------------------
+ *  | op_state  |   order_code         order_state |    <  |
+ *  |           |                                  |  <    |
+ *  | qty       |   organisation                   |    <  |
+ *  --------------------------------------------------------
  *
- * It provides a drawer from the right side which is populated
- * with the actions provided by the backend
+ * @module Components/goodcity/orders-package-block
+ * @augments ember/Component
+ * @param {Model} orderPkg the orders_package to display
+ * @description
+ * <br> It provides a drawer from the right side which is populated
+ * <br> with the actions provided by the backend
+ * <br>
+ * <br> Clicking on an action will run it on the API side
  *
- * Clicking on an action will run it on the API side
- *
- * @property {Model} orderPkg the orders_package to display
- *
- * Usage:
+ * @example
  *  {{goodcity/orders-package-block orderPkg=orderPkg }}
  */
 export default Ember.Component.extend(AsyncMixin, {
@@ -73,6 +75,7 @@ export default Ember.Component.extend(AsyncMixin, {
    *
    * CANCELLED is returned if the user closes the UI
    *
+   * @private
    * @returns {Promise<String>}
    */
   async selectOrder() {
@@ -88,6 +91,7 @@ export default Ember.Component.extend(AsyncMixin, {
    *
    * CANCELLED is returned if the user closes the UI
    *
+   * @private
    * @returns {Promise<String>}
    */
   async selectLocation() {
@@ -101,6 +105,7 @@ export default Ember.Component.extend(AsyncMixin, {
    *
    * CANCELLED is returned if the user closes the UI
    *
+   * @private
    * @returns {Promise<number>}
    */
   selectQuantity() {
@@ -132,6 +137,11 @@ export default Ember.Component.extend(AsyncMixin, {
    * to successfully
    *
    * CANCELLED if the user did not provide the
+   *
+   * @private
+   * @memberof OrdersPackageBlock
+   * @param {string} actionName the action being run
+   * @returns the options to send to the api
    */
   async fulfillParams(actionName) {
     const paramNames = _.get(ACTIONS_SETTINGS, `${actionName}.params`, []);
@@ -164,6 +174,10 @@ export default Ember.Component.extend(AsyncMixin, {
   /**
    * Runs the desired action
    *
+   * @memberof OrdersPackageBlock
+   * @private
+   * @param {string} actionName the action to run
+   * @returns {Promise<Package>} the updated package
    */
   async runAction(actionName) {
     const params = await this.fulfillParams(actionName);

app/components/let-alias.js

@@ -1,9 +1,9 @@
 import Ember from "ember";
 
 /**
- * Small helper component allowing to rename variables within the .hbs file
- *
- * Usage:
+ * @module Components/let-alias
+ * @description Small helper component allowing to rename variables within the .hbs file
+ * @example
  *
  * {{#let-alias model.someReallyLongPropertyName as |short| }}
  *    <div> This is {{short}} </div>

app/components/toggle-switch.js

@@ -4,6 +4,8 @@ import _ from "lodash";
 /**
  * Fancy toggle-switch component, wraps a checkbox internally
  *
+ * @module Components/toggle-switch
+ * @augments ember/Component
  * @property {boolean} value a property the component will bind to
  * @property {function} [afterChange] a callback triggered after value changes
  * <br> We typically listen to data change with Ember observers in the
@@ -12,6 +14,18 @@ import _ from "lodash";
  * <br> This callback can be used to react to changes that exclusively belong
  * <br> to the checkbox
  *
+ * @example
+ *
+ * {{toggle-switch
+ *    disabled=(unless allowPublish true)
+ *    on-icon='eye'
+ *    off-icon='eye-slash'
+ *    on-text=(t 'item_filters.published')
+ *    off-text=(t 'item_filters.private')
+ *    value=model.allowWebPublish
+ *    after-change=(action 'persistModel')
+ * }}
+ *
  */
 export default Ember.Component.extend({
   attributeBindings: ["value"],

app/controllers/goodcity_controller.js

@@ -1,17 +1,17 @@
-import Ember from 'ember';
-import RSVP from 'rsvp';
-import _ from 'lodash';
+import Ember from "ember";
+import RSVP from "rsvp";
+import _ from "lodash";
 
 /**
- * Generic controller base. Should hopefully help avoid re-writing code in the future
- * Has:
- *  - Message box
- *  - Loading spinner
- *  - CRUD methods for controlling records
- *
+ * @module Controllers/GoodcityController
+ * @augments ember/Controller
+ * @description Generic controller base. Should hopefully help avoid re-writing code in the future
+ *  <br> Has:
+ *  <br> - Message box
+ *  <br> - Loading spinner
+ *  <br> - CRUD methods for controlling records
  */
 export default Ember.Controller.extend({
-
   // ---- Services
 
   messageBox: Ember.inject.service(),
@@ -23,15 +23,25 @@ export default Ember.Controller.extend({
 
   // ---- Generic Helpers
 
+  /**
+   * @instance
+   * @description displays the loading spinner on the screen
+   */
   showLoadingSpinner() {
     if (Ember.testing) {
       return;
     }
     if (!this.loadingView) {
-      this.loadingView = Ember.getOwner(this).lookup('component:loading').append();
+      this.loadingView = Ember.getOwner(this)
+        .lookup("component:loading")
+        .append();
     }
   },
 
+  /**
+   * @instance
+   * @description hides the loading spinner off the screen
+   */
   hideLoadingSpinner() {
     if (Ember.testing) {
       return;
@@ -43,38 +53,45 @@ export default Ember.Controller.extend({
   },
 
   showError(message, cb) {
-    this.get("messageBox").alert(message || this.get("i18n").t("unexpected_error"), cb);
+    this.get("messageBox").alert(
+      message || this.get("i18n").t("unexpected_error"),
+      cb
+    );
   },
 
   onError(response = {}) {
-    const errors = _.map(response.errors, (err) => _.isString(err) ? err : err.detail);
+    const errors = _.map(response.errors, err =>
+      _.isString(err) ? err : err.detail
+    );
     this.showError(errors[0]);
   },
 
   // ---- CRUD
 
   createRecord(modelName, payload) {
-    const newRecord = this.get('store').createRecord(modelName, payload);
+    const newRecord = this.get("store").createRecord(modelName, payload);
     this.showLoadingSpinner();
-    return newRecord.save()
+    return newRecord
+      .save()
       .catch(r => {
         this.onError(r);
       })
-      .then(() => this.hideLoadingSpinner()); 
+      .then(() => this.hideLoadingSpinner());
   },
 
   updateRecord(record, updates = {}, opts = {}) {
     _.each(updates, (v, k) => record.set(k, v));
     this.showLoadingSpinner();
-    return record.save()
+    return record
+      .save()
       .then(() => {
-        _.get(opts, 'onSuccess', _.noop)();
+        _.get(opts, "onSuccess", _.noop)();
       })
       .catch(e => {
         if (!opts.noRollback) {
           record.rollbackAttributes();
         }
-        _.get(opts, 'onFailure', _.noop)(e);
+        _.get(opts, "onFailure", _.noop)(e);
         this.onError(e);
       })
       .finally(() => this.hideLoadingSpinner());
@@ -90,5 +107,4 @@ export default Ember.Controller.extend({
   back() {
     history.back();
   }
-
 });

app/controllers/items/index.js

@@ -2,6 +2,10 @@ import config from "../../config/environment";
 import _ from "lodash";
 import SearchMixin from "stock/mixins/search_resource";
 
+/**
+ * @module Controllers/items/ItemsSearchController
+ * @augments ember/Controller
+ */
 export default Ember.Controller.extend(SearchMixin, {
   queryParams: ["searchInput", "itemSetId"],
   itemSetId: null,
@@ -13,11 +17,11 @@ export default Ember.Controller.extend(SearchMixin, {
   },
 
   /**
-   * @type {Boolean}, expected in SearchMixin
+   * @property {Boolean} SearchMixin configuration
    **/
   autoLoad: true,
   /**
-   * @type {Number}, perPage in response
+   * @property {Number} SearchMixin configuration, perPage in response
    **/
   perPage: 25,
 
@@ -49,6 +53,12 @@ export default Ember.Controller.extend(SearchMixin, {
   }),
 
   actions: {
+    /**
+     * Load the next page of the list
+     *
+     * @param {number} pageNo the page to load
+     * @returns {Promise<Model[]>}
+     */
     loadMoreItems(pageNo) {
       const params = this.trimQuery(
         _.merge(