Merge pull request #31367 from dwi2/bug1193162

Bug 1193162 - [JSDOC] write documentation of app-deck in jsdoc format

tv_apps/app-deck/README.md

@@ -1,10 +1,28 @@
 # Apps (App Deck)
 
 App deck is a smart screen app that provides functionality of
+
 1. displaying all installed app.
 2. uninstalling app
 3. pinning app to `Home`
 
+From JS point-of-view, App deck is composed of three classes:
+* AppDeck
+* ContextMenu
+* PromotionList
+
+AppDeck class is the main controller of this app. It handles all behavior and UI of app-deck. The other two classes work as submodule of AppDeck and are both initialized by AppDeck. AppDeck also utilize other classes or module that help it do things.
+
+ContextMenu class handles things related to 'contextmenu' event. User could pin/unpin/remove apps via context menu. Thus the logic and UI of context menu are all in this classes. We use [IAC](http://mzl.la/1TKR6zw) to pin an app and [MozActivity](http://mzl.la/1Pu8ecc) to unpin an app.
+
+PromotionList class handles UI and animation of upper half (section#jumbotron) of app deck. It is designed to display recommended apps on Marketplace. However we have no time to finish this part yet so currently we only make it looks and feels like it should be.
+
+From HTML point-of-view, app deck is divided in two sections:
+* promotion list (section#jumbotron)
+* app lists (section#app-deck-grid-view-container)
+
+We use [XScrollable](http://bit.ly/1DWHgsH) to display apps and response to user interaction in app lists. Every app in app lists is encapsulated in [SmartButton](http://bit.ly/1Ld0WYX).
+
 ## JSDOC
 
 Generated jsdoc is hosted on [http://mozilla-b2g.github.io/gaia/app-deck/](http://mozilla-b2g.github.io/gaia/app-deck/). You can generate it locally with the following command:

tv_apps/app-deck/js/app_deck.js

@@ -8,7 +8,20 @@
   const DEFAULT_ICON_PATH = 'style/icons/appic_developer.png';
 
   /**
-   * [AppDeck main entry point of AppDeck]
+   * @class AppDeck
+   *
+   * @requires SpatialNavigator
+   * @requires SharedUtils
+   * @requires Applications
+   * @requires {@link http://bit.ly/1DWJJmF|evt}
+   * @requires XScrollable
+   * @requires KeyNavigationAdapter
+   * @requires {@link ContextMenu}
+   * @requires CardManager
+   * @requires {@link PromotionList}
+   *
+   * @fires AppDeck#focus-on-pinable
+   * @fires AppDeck#focus-on-nonpinable
    */
   var AppDeck = function() {
   };
@@ -30,16 +43,27 @@
 
     _cardManager: undefined,
 
+    /**
+     * Initialize AppDeck. This is the main entry of the whole app.
+     *
+     * @public
+     * @method  AppDeck#init
+     */
     init: function ad_init() {
       var that = this;
       this._keyNavigationAdapter = new KeyNavigationAdapter();
       this._keyNavigationAdapter.init();
       this._cardManager = new CardManager();
+      // initialize CardManager in 'readonly' mode. Notice that only smart-home
+      // could use 'readwrite' mode.
       this._cardManager.init('readonly').then(function() {
         that._cardManager.on('cardlist-changed',
                              that.onCardListChanged.bind(that));
       });
 
+      // Because module Applications use manifest helper to get localized app
+      // name. We cannot initialize Applications until l10n is ready.
+      // See bug 1170083.
       var afterApplicationsInit = function() {
         var apps = Applications.getAllAppEntries();
         var appGridElements = apps.map(that._createAppGridElement.bind(that));
@@ -86,6 +110,17 @@
       });
     },
 
+    /**
+     * Fills element with icon which is fetched from
+     * [app](http://mzl.la/1DJP6oZ)
+     *
+     * @private
+     * @method  AppDeck#_fillAppButtonIcon
+     * @param  {DOMApplication} app - app instance where we fetch icon from,
+     *                              see [here](http://mzl.la/1DJP6oZ)
+     * @param  {SmartButton} elem - [SmartButton](http://bit.ly/1Ld0WYX)
+     *                            instance to be filled
+     */
     _fillAppButtonIcon: function ad_fillAppButtonIcon(app, elem) {
       Applications.getIconBlob(app.manifestURL, app.entryPoint, ICON_SIZE,
         function(blob) {
@@ -100,6 +135,16 @@
         });
     },
 
+    /**
+     * Create SmartButton element based on input [app](http://mzl.la/1DJP6oZ)
+     * instance
+     *
+     * @private
+     * @method  AppDeck#_createAppGridElement
+     * @param  {DOMApplication} app - [app](http://mzl.la/1DJP6oZ|)
+     *                                    instance
+     * @return {SmartButton} - see [here](http://bit.ly/1Ld0WYX)
+     */
     _createAppGridElement: function ad_createAppGridElement(app) {
       var appButton = document.createElement('smart-button');
       appButton.dataset.manifestURL = app.manifestURL;
@@ -121,22 +166,47 @@
       }
     },
 
+    /**
+     * Notify other module that currently focused element is pinable (could be
+     * pinned on Home) or nonpinable (could not be pinned on Home)
+     *
+     * @public
+     * @method  AppDeck#fireFocusEvent
+     * @param  {HTMLElement} elem - currently focused element
+     */
     fireFocusEvent: function ad_fireFocusEvent(elem) {
       var that = this;
       if (elem && elem.dataset && elem.dataset.manifestURL) {
         this._cardManager.isPinned({
           manifestURL: elem.dataset.manifestURL,
           entryPoint: elem.dataset.entryPoint
         }).then(function(pinned) {
+          /**
+           * This event fires whenever focus in AppDeck move to a pinable
+           * element (representing na app).
+           * @event AppDeck#focus-on-pinable
+           * @type {Object}
+           * @property {Boolean} pinned - Is current focused pinable element
+           *                            pinned or not
+           * @property {String} manifestURL - manifestURL of current focused
+           *                                element
+           * @property {String} name - name of current focused pinable element
+           * @property {Boolean} removable - Is current focused pinable element
+           *                               removable or not
+           */
           that.fire('focus-on-pinable', {
             pinned: pinned,
             manifestURL: elem.dataset.manifestURL,
+            // entryPoint is deprecated
             entryPoint: elem.dataset.entryPoint,
             name: elem.dataset.name,
             removable: elem.dataset.removable === 'true'
           });
         });
       } else {
+        /**
+         * @event AppDeck#focus-on-nonpinable
+         */
         this.fire('focus-on-nonpinable');
       }
     },
@@ -253,11 +323,28 @@
       });
     },
 
+    /**
+     * Shorthand function to get all SmartButtons of apps
+     *
+     * @private
+     * @method  AppDeck#_findAllAppGridElements
+     * @return {Array} array of SmartButton
+     */
     _findAllAppGridElements: function ad_findallAppGridElements() {
       return SharedUtils.nodeListToArray(
         document.getElementsByClassName('app-button'));
     },
 
+    /**
+     * Shorthand function to find specific SmartButton representing the app
+     *
+     * @private
+     * @method  AppDeck#_findAppGridElement
+     * @param  {DOMApplication} app  the [app](http://mzl.la/1DJP6oZ) instance
+     *                               which we want to find SmartButton is
+     *                               represented for
+     * @return {SmartButton}
+     */
     _findAppGridElement: function ad_findAppGridElement(app) {
       var elements = this._findAllAppGridElements();
       var found;

tv_apps/app-deck/js/context_menu.js

@@ -4,6 +4,15 @@
 /* jshint nonew: false */
 
 (function(exports) {
+
+
+  /**
+   * It handles everything related to contextmenu in app-deck.
+   *
+   * @class ContextMenu
+   * @requires Applications
+   * @requires SharedUtils
+   */
   var ContextMenu = function() {
   };
 
@@ -16,6 +25,13 @@
     _appDeck: undefined,
     _app: undefined,
 
+    /**
+     * Initialize ContextMenu
+     *
+     * @public
+     * @method  ContextMenu#init
+     * @param  {AppDeck} appDeck - instance of {@link AppDeck}
+     */
     init: function cm_init(appDeck) {
       this.mainSection.addEventListener('contextmenu',
         this.onContextMenu.bind(this));
@@ -31,6 +47,14 @@
 
     _selfApp: undefined,
 
+    /**
+     * Underlying function which actual send string message on 'appdeck-channel'
+     *
+     * @private
+     * @method  ContextMenu#_connectAndSend
+     * @param  {String} message - the message which will be sent on
+     *                          'appdeck-channel'
+     */
     _connectAndSend: function cm_sendMessage(message) {
       this._selfApp.connect('appdeck-channel').then(function (ports) {
         ports.forEach(function(port) {
@@ -39,6 +63,16 @@
       });
     },
 
+    /**
+     * Send message on 'appdeck-channel' using Inter-App Communication.
+     * smart-home will monitor this channel. Currently we use this channel to
+     * tell smart-home to what app we would like to unpin.
+     *
+     * @public
+     * @method  ContextMenu#sendMessage
+     * @param  {String} type - message type, which must be 'unpin' for now.
+     * @param  {Object} data - message data in JSON object format
+     */
     sendMessage: function cm_sendMessage(type, data) {
       var that = this;
       var message = {
@@ -56,11 +90,28 @@
       }
     },
 
+    /**
+     * Shorthand function to derive launchURL from [app](http://mzl.la/1DJP6oZ)
+     * instance
+     *
+     * @private
+     * @method ContextMenu#_composeLaunchURL
+     * @param  {DOMApplication} app - see [here](http://mzl.la/1DJP6oZ)
+     * @return {String}  launchURL
+     */
     _composeLaunchURL: function cm_composeLaunchURL(app) {
       return app.manifestURL.replace('manifest.webapp', '') + app.entryPoint;
     },
 
-    _sendUnpinMessage: function cm_sendUnpinActivity(app) {
+    /**
+     * To tell smart-home what app we would like to unpin
+     *
+     * @private
+     * @method  ContextMetnu#_sendUnpinMessage
+     * @param  {DOMApplication} app - the [app](http://mzl.la/1DJP6oZ) we'd like
+     *                              to unpin from Home
+     */
+    _sendUnpinMessage: function cm_sendUnpinMessage(app) {
       // Notice that here we didn't specify launchURL because we assume all
       // 'Application' in app-deck are launched by calling app.launch().
       // However, in the case of other deck-like app, if we are going to pin
@@ -71,6 +122,16 @@
       });
     },
 
+    /**
+     * Based on currently focused SmartButton, we'll decide we are going to
+     * pin or unpin the app. This function is invoked when we get 'click' event
+     * on pinToHomeElem. Notice that we use `MozActivity` to pin app because we
+     * want to bring users to Home when they finish pinning. However we unpin
+     * app via IAC because we want users stay in AppDeck after unpinning.
+     *
+     * @public
+     * @method  ContextMenu#pinOrUnpin
+     */
     pinOrUnpin: function cm_pinOrUnpin() {
       if (this._app) {
         var app = this._app;
@@ -106,6 +167,11 @@
       }
     },
 
+    /**
+     * Uninstall app represented by current focused SmartButton
+     * @public
+     * @method  ContextMenu#uninstall
+     */
     uninstall: function cm_uninstall() {
       if (this._app && this._app.removable) {
         var app = this._app;

tv_apps/app-deck/js/promotion_list.js

@@ -48,6 +48,10 @@
     }
   ];
 
+  /**
+   * PromotionList controls everything on the upper half of AppDeck
+   * @class PromotionList
+   */
   function PromotionList() {}
 
   var proto = PromotionList.prototype;