Update to jsdocs

.gitignore

@@ -5,4 +5,5 @@ npm-debug.log
 phantomjsdriver.log
 node_modules
 dist
+docs/src
 lib

README.md

@@ -1,12 +1,12 @@
 # stratos-ui
 
 ## Pre-requisite
-1. Create a Docker machine. If running on OSX and VirtualBox, you will likely need to create a Docker machine with the `--virtualbox-cpu-count` flag.
+* Create a Docker machine. If running on OSX and VirtualBox, you may need to set the `--virtualbox-cpu-count` flag.
 ```
 docker-machine create --driver virtualbox --virtualbox-cpu-count "2" default
 eval $(docker-machine env default)
 ```
-2. Create and start [stratos-server](https://github.com/hpcloud/stratos-server).
+* Create and start [stratos-server](https://github.com/hpcloud/stratos-server).
 
 
 ## Build Docker image
@@ -67,4 +67,11 @@ $ ./node_modules/.bin/protractor protractor.conf.js
 ```
 $ cd tools
 $ ./node_modules/.bin/gulp lint
+```
+
+## Generate Documentation (Experimental)
+Locally, run the following command to generate documentation in the `docs/src` folder.
+```
+cd tools
+./node_modules/.bin/jsdoc ../src/app ../src/*.js -r -d ../docs/src
 ```

docs/README.md

@@ -9,28 +9,28 @@ The Angular-based application is composed of three layers and an event bus. The
 ### Source Code Structure
 ```
   src
-      └── app
-          ├── api
-          ├── event
-          ├── model
-          ├── view
-          ├── app.scss
-          ├── app.module.js
-          └── app.spec.js
-      └── lib
-      └── plugins
-          └── my-app
-              ├── api
-              │   └── api.module.js
-              ├── event
-              │   └── event.module.js
-              ├── model
-              │   └── model.module.js
-              ├── view
-              │   └── view.module.js
-              ├── my-app.scss
-              ├── my-app.module.js
-              └── plugin.config.js
+    └── app
+        ├── api
+        ├── event
+        ├── model
+        ├── view
+        ├── app.scss
+        ├── app.module.js
+        └── app.spec.js
+    └── lib
+    └── plugins
+        └── my-app
+            ├── api
+            │   └── api.module.js
+            ├── event
+            │   └── event.module.js
+            ├── model
+            │   └── model.module.js
+            ├── view
+            │   └── view.module.js
+            ├── my-app.scss
+            ├── my-app.module.js
+            └── plugin.config.js
 ```
 
 ### Style Sheets

src/app/api/api.module.js

@@ -1,6 +1,12 @@
 (function () {
   'use strict';
 
+  /**
+   * @namespace app.api
+   * @memberof app
+   * @name api
+   * @description The API layer of the UI platform that handles HTTP requests
+   */
   angular
     .module('app.api', [], config);
 
@@ -12,18 +18,17 @@
     $httpProvider.interceptors.push(interceptor);
   }
 
-  /**
-   * A $http interceptor, which emits a global http error event when
-   * response.status >= 400
-   *
-   * check https://docs.angularjs.org/api/ng/service/$http for details on
-   * $http interceptors.
-   */
   interceptor.$inject = [
     '$q',
     'app.event.eventService'
   ];
 
+  /**
+   * A $http interceptor, which emits a global HTTP error event when
+   * response.status >= 400
+   *
+   * See https://docs.angularjs.org/api/ng/service/$http for details
+   */
   function interceptor($q, eventService) {
     return {
       responseError: responseError

src/app/api/api-manager.service.js → src/app/api/apiManager.service.js

@@ -3,8 +3,13 @@
 
   angular
     .module('app.api')
-    .factory('app.api.api-manager', apiManagerFactory);
+    .factory('app.api.apiManager', apiManagerFactory);
 
+  /**
+   * @memberof app.api
+   * @name apiManager
+   * @description The manager that handles registration and retrieval of APIs
+   */
   function apiManagerFactory() {
     var apis = {};
 

src/app/app.module.js

@@ -1,6 +1,10 @@
 (function () {
   'use strict';
 
+  /**
+   * @namespace app
+   * @name app
+   */
   angular
     .module('app', [
       'app.api',

src/app/event/event.module.js

@@ -1,6 +1,13 @@
 (function () {
   'use strict';
 
+  /**
+   * @namespace app.event
+   * @memberof app
+   * @name event
+   * @description The event bus that allows communication between the
+   * view, model and API layers
+   */
   angular
     .module('app.event', []);
 

src/app/event/event.service.js

@@ -1,7 +1,6 @@
 (function () {
   'use strict';
 
-
   var events = {
     LOGGED_IN: 'LOGGED_IN',
     LOGGED_OUT: 'LOGGED_OUT',
@@ -20,17 +19,18 @@
   ];
 
   /**
-   * @name app.event.eventService
+   * @namespace app.event.eventService
+   * @memberof app.event
+   * @name eventService
+   * @description The event bus service
+   * @property {object} events - the default set of events (i.e. HTTP status codes)
    * @example
-   ```js
-   // subscribe to an event:
-   eventService.$on(events.HTTP_401, handler);
-
-   // emit an event
-   eventService.$emit(events.HTTP_401);
-   ```
+   * // subscribe to an event
+   * eventService.$on(events.HTTP_401, handler);
+   *
+   * // emit an event
+   * eventService.$emit(events.HTTP_401);
    */
-
   function eventServiceFactory($rootScope) {
     var eventService = $rootScope.$new();
     eventService.events = events;

src/app/model/account/account.model.js

@@ -1,6 +1,12 @@
 (function () {
   'use strict';
 
+  /**
+   * @namespace app.model.account
+   * @memberOf app.model
+   * @name account
+   * @description Account model
+   */
   angular
     .module('app.model')
     .run(registerAccountModel);
@@ -13,7 +19,12 @@
 
     modelManager.register('app.model.account', new Account());
 
-    // TODO: this is just a fake implementation for Account model.
+    /**
+     * @namespace app.model.account.Account
+     * @memberof app.model.account
+     * @name app.model.account.Account
+     * @todo This is just a fake implementation for Account model
+     */
     function Account() {
       this.name = null;
       this.loggedIn = false;

src/app/model/model.module.js

@@ -1,6 +1,14 @@
 (function () {
   'use strict';
 
+  /**
+   * @namespace app.model
+   * @memberof app
+   * @name model
+   * @description The model layer of the UI platform that contains
+   * the business data objects and methods to retrieve/update the
+   * data
+   */
   angular
     .module('app.model', []);
 

src/app/model/modelManager.js

@@ -7,6 +7,12 @@
 
   modelManagerFactory.$inject = [];
 
+  /**
+   * @namespace app.model.modelManager
+   * @memberof app.model
+   * @name app.model.modelManager
+   * @description The manager that handles registration and retrieval of models
+   */
   function modelManagerFactory() {
     var models = {};
 
@@ -16,10 +22,22 @@
       retrieve: retrieve
     };
 
+    /**
+     * @function register
+     * @memberof app.model.modelManager
+     * @param {string} name - the name of the model to register
+     * @param {object} model - the model object to register
+     */
     function register(name, model) {
       models[name] = model;
     }
 
+    /**
+     * @function retrieve
+     * @memberof app.model.modelManager
+     * @param {string} name - the name of the model to retrieve
+     * @returns {object} the requested model
+     */
     function retrieve(name) {
       return models[name];
     }

src/app/model/navigation/navigation.model.js

@@ -1,6 +1,12 @@
 (function () {
   'use strict';
 
+  /**
+   * @namespace app.model.navigation
+   * @memberOf app.model
+   * @name navigation
+   * @description Navigation model
+   */
   angular
     .module('app.model')
     .run(registerModel);
@@ -11,46 +17,49 @@
 
   function registerModel(modelManager) {
     /**
-     * @name 'app.model.navigation'
-     * @description
-     *
-     * This model hosts application navigation tree.
+     * Register 'app.model.navigation' with the model manager service.
+     * This model hosts the application's navigation tree.
      */
     modelManager.register('app.model.navigation', new Menu());
   }
 
+  /**
+   * @namespace app.model.navigation.Menu
+   * @memberof app.model.navigation
+   * @name app.model.navigation.Menu
+   */
   function Menu() {}
 
   Menu.prototype = [];
 
   angular.extend(Menu.prototype, {
     /**
-     * Appends a new menu item into the menu list. Each menu item will
-     * has a sub-menu which is also of type Menu and it is empty when
-     * initialized. When the sub-menu is populated, clicking on the menu
-     * item will show the sub-menu, a drop-down list for instance.
-     *
-     * @param name {String} used to identify the item.
-     * @param href {String} the href / ng-router state.
-     * @param text {String} display text.
-     * @returns {Menu}
-     *
-     * Each menu item has a sub-menu defined is `items`.
+     * @function addMenuItem
+     * @memberof app.model.navigation.Menu
+     * @description Appends a new menu item into the menu list. Each menu item
+     * is a sub-menu which is also of type Menu and is empty initially.
+     * @param {string} name - the name/ID of the menu item
+     * @param {string} href - the href / ng-router state
+     * @param {string} text - the displayed text of the menu item
+     * @param {string} icon - the icon of the menu item
+     * @returns {app.model.navigation.Menu}
      */
     addMenuItem: function (name, href, text, icon) {
       this.push({
         name: name,
         href: href,
         text: text,
         icon: icon,
-        items: new Menu()
+        items: new Menu()   // sub-menu
       });
       return this;
     },
 
     /**
-     * Cleans up menu items.
-     * @returns {Menu}
+     * @function reset
+     * @memberof app.model.navigation.Menu
+     * @description Clear the menu list
+     * @returns {app.model.navigation.Menu}
      */
     reset: function () {
       this.length = 0;