From 10343207b9bd046e4a5bf9ca68de74429a9f0e7e Mon Sep 17 00:00:00 2001 From: Kelly Domico Date: Thu, 21 Jan 2016 11:47:28 -0800 Subject: [PATCH 1/8] Initial update of jsdoc in code --- tools/create-plugin.js | 82 +++++++++++++++++++++--------------------- 1 file changed, 40 insertions(+), 42 deletions(-) diff --git a/tools/create-plugin.js b/tools/create-plugin.js index 1923a111f5..d6ca153da9 100644 --- a/tools/create-plugin.js +++ b/tools/create-plugin.js @@ -6,34 +6,32 @@ var writeFile = require('fs').writeFile , cd = process.chdir; /** - * - * This script scaffolds a plugin application. For example if you want to - * create a plugin with name helion.my-app, by running: - ``` - node create-plugin - ``` - * you will be prompt for a unique plugin application name. once you provide, - * it will create: - ``` - plugins - └── helion.my-app - ├── api - │   └── api.module.js - ├── event - │   └── event.module.js - ├── model - │   └── model.module.js - ├── view - │ └── view.module.js - ├── helion.my-app.module.js - ├── helion.my-app.scss - └── plugin.config.js - ``` - * Then, after re-running - ``` - node_modules/.bin/gulp - ``` - * the plugin will be integrated onto the ui platform. + * This script scaffolds a plugin application. For example, if you want to + * create a plugin with the name helion.my-app, run: + * ``` + * node create-plugin + * ``` + * You will be prompted for a unique plugin application name. On submit, + * it will create the following file structure: + * ``` + * plugins + * └── helion.my-app + * ├── api + * │   └── api.module.js + * ├── event + * │   └── event.module.js + * ├── model + * │   └── model.module.js + * ├── view + * │ └── view.module.js + * ├── helion.my-app.module.js + * ├── helion.my-app.scss + * └── plugin.config.js + * ``` + * Finally, run the default Gulp task to integrate the plugin with the UI platform: + * ``` + * node_modules/.bin/gulp + * ``` */ prompt.start(); @@ -72,12 +70,12 @@ prompt.get(['Input a unique plugin application name'], function (err, result) { } /** - * create an angular module file, in given folder, with given file name, - * angular module name, and dependent sub module names. + * Create an Angular module file, in given folder, with given file name, + * Angular module name, and dependent sub-module names. * - * @param folderName {String} - * @param fileName {String} the generated file name is suffixed with `.module.js`. - * @param moduleName {String} the generated module name is prefixed with `helio.`. + * @param folderName {String} the folder name + * @param fileName {String} the generated file name that will be suffixed with `.module.js` + * @param moduleName {String} the generated module name that will be prefixed with `helion.` * @param subModules {Array}, [optional], if provided, the generated dependency * modules will be prefixed with the generated module name. * @@ -130,7 +128,7 @@ prompt.get(['Input a unique plugin application name'], function (err, result) { } /** - * runs shell command mkdir. + * Run shell command mkdir * @param folderName the name of the folder to create. */ function mkdir(folderName) { @@ -138,7 +136,7 @@ prompt.get(['Input a unique plugin application name'], function (err, result) { } /** - * creates a root scss file with one comment line in it. + * Create a root scss file with one comment line in it * @param fileName */ function createRootScssFile(fileName) { @@ -147,21 +145,21 @@ prompt.get(['Input a unique plugin application name'], function (err, result) { } /** - * creates a JavaScript file with the given file name and code. - * @param filesName {String} the file name. - * @param code {String} the JavaScript code. + * Create a Javascript file with the given file name and code wrapped in an IIFE + * @param filesName, the file name + * @param code, the JavaScript code. */ function createJavaScriptFile(fileName, code) { writeFile(fileName, wrapCodeAsIIFE(code)); } /** - * wraps code as Immediately-invoked function expressions. + * Wrap code with immediately-invoked function expression * @param code {String} the code to wrap. - * @returns {String} wrapped code. + * @returns {String} the wrapped code. * @description * - * wrapped code looks like: + * Wrapped code looks like: ``` (function () { 'use strict'; @@ -182,7 +180,7 @@ prompt.get(['Input a unique plugin application name'], function (err, result) { } /** - * wrap a string with single quotes. + * Wrap a string with single quotes * @param str {String} the string to wrap * @returns {String} a new wrapped string */ From fb2105c500676bc25d44d99e42ae1225c5e58b70 Mon Sep 17 00:00:00 2001 From: Kelly Domico Date: Thu, 21 Jan 2016 18:41:33 -0800 Subject: [PATCH 2/8] Updated JS files with jsdocs comments --- README.md | 4 +- src/app/api/api.module.js | 5 + ...nager.service.js => apiManager.service.js} | 8 +- src/app/app.module.js | 3 + src/app/event/event.module.js | 5 + src/app/event/event.service.js | 21 +-- src/app/model/model.module.js | 5 + src/app/model/modelManager.js | 7 + src/app/model/navigation/navigation.model.js | 30 ++-- src/app/view/view.module.js | 5 + src/config.js | 51 ++++--- tools/create-plugin.js | 133 +++++++++--------- 12 files changed, 159 insertions(+), 118 deletions(-) rename src/app/api/{api-manager.service.js => apiManager.service.js} (64%) diff --git a/README.md b/README.md index 6f5a08c3d5..b85a82541d 100644 --- a/README.md +++ b/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 diff --git a/src/app/api/api.module.js b/src/app/api/api.module.js index 69ed2611ee..d923f66286 100644 --- a/src/app/api/api.module.js +++ b/src/app/api/api.module.js @@ -1,6 +1,11 @@ (function () { 'use strict'; + /** + * @namespace app.api + * @memberof app + * @name api + */ angular .module('app.api', [], config); diff --git a/src/app/api/api-manager.service.js b/src/app/api/apiManager.service.js similarity index 64% rename from src/app/api/api-manager.service.js rename to src/app/api/apiManager.service.js index 54fb45521c..4a9e810d6b 100644 --- a/src/app/api/api-manager.service.js +++ b/src/app/api/apiManager.service.js @@ -3,8 +3,14 @@ angular .module('app.api') - .factory('app.api.api-manager', apiManagerFactory); + .factory('app.api.apiManager', apiManagerFactory); + /** + * @memberof app.api + * @name apiManager + * @description The API layer of the UI platform that handles + * HTTP requests + */ function apiManagerFactory() { var apis = {}; diff --git a/src/app/app.module.js b/src/app/app.module.js index a5b66a166f..db27015cc4 100644 --- a/src/app/app.module.js +++ b/src/app/app.module.js @@ -1,6 +1,9 @@ (function () { 'use strict'; + /** + * @namespace app + */ angular .module('app', [ 'app.api', diff --git a/src/app/event/event.module.js b/src/app/event/event.module.js index 9b690a90fc..9790a2b636 100644 --- a/src/app/event/event.module.js +++ b/src/app/event/event.module.js @@ -1,6 +1,11 @@ (function () { 'use strict'; + /** + * @namespace app.event + * @memberof app + * @name event + */ angular .module('app.event', []); diff --git a/src/app/event/event.service.js b/src/app/event/event.service.js index da4fddf993..aff349a780 100644 --- a/src/app/event/event.service.js +++ b/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,19 @@ ]; /** - * @name app.event.eventService + * @memberof app.event + * @name eventService + * @description The event bus that allows communication between the + * view, model and API layers * @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; diff --git a/src/app/model/model.module.js b/src/app/model/model.module.js index 4223c98f10..50cf48b59e 100644 --- a/src/app/model/model.module.js +++ b/src/app/model/model.module.js @@ -1,6 +1,11 @@ (function () { 'use strict'; + /** + * @namespace app.model + * @memberof app + * @name model + */ angular .module('app.model', []); diff --git a/src/app/model/modelManager.js b/src/app/model/modelManager.js index 84885800f1..160601292c 100644 --- a/src/app/model/modelManager.js +++ b/src/app/model/modelManager.js @@ -7,6 +7,13 @@ modelManagerFactory.$inject = []; + /** + * @memberof app.model + * @name modelManager + * @description The model layer of the UI platform that contains + * the business data objects and methods to retrieve/update the + * data + */ function modelManagerFactory() { var models = {}; diff --git a/src/app/model/navigation/navigation.model.js b/src/app/model/navigation/navigation.model.js index 7e282d639e..dc6bd126de 100644 --- a/src/app/model/navigation/navigation.model.js +++ b/src/app/model/navigation/navigation.model.js @@ -11,28 +11,30 @@ 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 Menu + * @name 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. + * @function addMenuItem + * @memberof 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 {Menu} * * Each menu item has a sub-menu defined is `items`. @@ -49,7 +51,9 @@ }, /** - * Cleans up menu items. + * @function reset + * @memberof Menu + * @description Clear the menu list * @returns {Menu} */ reset: function () { diff --git a/src/app/view/view.module.js b/src/app/view/view.module.js index 1f2112ba98..128db328d6 100644 --- a/src/app/view/view.module.js +++ b/src/app/view/view.module.js @@ -1,6 +1,11 @@ (function () { 'use strict'; + /** + * @namespace app.view + * @memberof app + * @name view + */ angular .module('app.view', []); diff --git a/src/config.js b/src/config.js index 8d02c1dac6..892677ebdc 100644 --- a/src/config.js +++ b/src/config.js @@ -1,6 +1,10 @@ (function (global) { 'use strict'; + /** + * @namespace env + * @property {string} HELION_UI_FRAMEWORK_BASE_PATH - the Helion UI framework path + */ var env = { registerApplication: registerApplication, @@ -13,34 +17,27 @@ }); /** - * @ngdoc registerApplication {Function} registers a plugin-able application to - * the platform. - * - * @param id {String} the id to identify the registered application. - * - * @param angularModuleName {String} defines the root angular module - * name of the plugin application. Each plugin app MUST have one and - * only one angular module name. + * @memberof env + * @name registerApplication + * @description + * Register a plugin application with the UI platform and include its + * Angular module as a dependency of the UI platform module. * - * This module will be added to the system as a dependency for the - * whole app the be initialized. - * - * @param basePath {String} defines the base path to the root folder - * where the plugin app resides or is installed. The basePath is - * relative to the src folder. - * - * IMPORTANT: Every plugin-able application should have a plugin.config.js - * resides with the application and register itself by: - - ```js - // register this plugin application to the platform: - - env && env.registerApplication && env.env.registerApplication( - 'My Application ID', - 'my-application-angular-module-name', - 'plugins/my-application/' - ); - ``` + * IMPORTANT: Every plugin application MUST include a `plugin.config.js` + * file at its root directory that will register itself with the UI platform. + * ``` + * env && env.registerApplication && env.env.registerApplication( + * 'My Application ID', + * 'my-application-angular-module-name', + * 'plugins/my-application/' + * ); + * ``` + * @param {string} id - the ID to identify the application being registered + * @param {string} angularModuleName - the unique Angular module name of the + * plugin application + * @param {string} basePath - the base path to the root folder where the + * plugin application resides or is installed. The basePath is relative to + * the 'src' folder. */ function registerApplication(id, angularModuleName, basePath) { env.plugins = env.plugins || {}; diff --git a/tools/create-plugin.js b/tools/create-plugin.js index d6ca153da9..7a2b19557a 100644 --- a/tools/create-plugin.js +++ b/tools/create-plugin.js @@ -6,16 +6,16 @@ var writeFile = require('fs').writeFile , cd = process.chdir; /** - * This script scaffolds a plugin application. For example, if you want to - * create a plugin with the name helion.my-app, run: + * This script generates a scaffold for a plugin application. For example, if + * you want to create a plugin with the name 'helion.my-app', run: * ``` - * node create-plugin + * node create-plugin * ``` * You will be prompted for a unique plugin application name. On submit, * it will create the following file structure: * ``` - * plugins - * └── helion.my-app + * plugins + * └── helion.my-app * ├── api * │   └── api.module.js * ├── event @@ -41,17 +41,20 @@ prompt.get(['Input a unique plugin application name'], function (err, result) { cd('../src/plugins'); - // create a folder with the module name + // Create a directory with the plugin application name mkdir(plugininName); cd(plugininName); createPluginConfigFile(); - // create `my-app.scss` + // Create `helion.my-app.scss` createRootScssFile(plugininName + '.scss'); - // create folders `api`, `event`, `model`, `view` and files - // `api/api.module.js`, `event/event.module.js`, `model/model.module.js`, `view/view.module.js`, + /** + * Create directories: `api`, `event`, `model`, `view` + * Create Angular module files: `api/api.module.js`, `event/event.module.js`, + * `model/model.module.js`, `view/view.module.js` + */ ['api', 'event', 'model', 'view'].forEach(function (one) { mkdir(one); createModuleFile(one, one, plugininName + '.' + one, null); @@ -73,44 +76,42 @@ prompt.get(['Input a unique plugin application name'], function (err, result) { * Create an Angular module file, in given folder, with given file name, * Angular module name, and dependent sub-module names. * - * @param folderName {String} the folder name - * @param fileName {String} the generated file name that will be suffixed with `.module.js` - * @param moduleName {String} the generated module name that will be prefixed with `helion.` - * @param subModules {Array}, [optional], if provided, the generated dependency - * modules will be prefixed with the generated module name. + * @param {string} folderName - the folder name + * @param {string} fileName - the generated file name, suffixed with `.module.js` + * @param {string} moduleName - the generated module name + * @param {Array} [subModules] - if provided, the generated dependency modules + * will be prefixed with the generated module name * * @example + * createModuleFile('api', 'api', 'my-app.api'); * - ```js - createModuleFile('api', 'api', 'my-app.api'); - - // creates api/api.module.js with code: - - (function () { - 'use strict'; - - angular - .module('helion.my-app.api', []); - - })(); - - createModuleFile('.', 'my-app.module', 'helion.my-app', - ['api', 'event', 'model', 'view']); - - // creates ./my-app.module.js with code: - - (function () { - 'use strict'; - - angular - .module('helion.my-app', [ - 'helion.my-app.api', - 'helion.my-app.event', - 'helion.my-app.model', - 'helion.my-app.view' - ]); - - })(); + * // Generates api/api.module.js with code: + * // + * // (function () { + * // 'use strict'; + * // + * // angular + * // .module('my-app.api', []); + * // + * // })(); + * + * createModuleFile('.', 'my-app', 'helion.my-app', + * ['api', 'event', 'model', 'view']); + * + * // Generates ./my-app.module.js with code: + * // + * // (function () { + * // 'use strict'; + * // + * // angular + * // .module('helion.my-app', [ + * // 'helion.my-app.api', + * // 'helion.my-app.event', + * // 'helion.my-app.model', + * // 'helion.my-app.view' + * // ]); + * // + * // })(); */ function createModuleFile(folderName, fileName, moduleName, subModules) { subModules = subModules || ''; @@ -122,22 +123,24 @@ prompt.get(['Input a unique plugin application name'], function (err, result) { } var code = [ ' angular', - ' .module(\'' +moduleName + '\', [' + subModules + ']);' + ' .module(\'' + moduleName + '\', [' + subModules + ']);' ]; createJavaScriptFile(folderName + '/' + fileName + '.module.js', code); } /** - * Run shell command mkdir - * @param folderName the name of the folder to create. + * Create a directory using mkdir + * + * @param {string} folderName - the name of the folder to create */ function mkdir(folderName) { bash('mkdir -p ' + folderName); } /** - * Create a root scss file with one comment line in it - * @param fileName + * Create a root SCSS file with one comment line in it + * + * @param {string} fileName - the SCSS file name */ function createRootScssFile(fileName) { var commentLine = '// ' + fileName; @@ -146,8 +149,9 @@ prompt.get(['Input a unique plugin application name'], function (err, result) { /** * Create a Javascript file with the given file name and code wrapped in an IIFE - * @param filesName, the file name - * @param code, the JavaScript code. + * + * @param {string} fileName - the Javascript file name + * @param {string} code - the JavaScript code */ function createJavaScriptFile(fileName, code) { writeFile(fileName, wrapCodeAsIIFE(code)); @@ -155,19 +159,17 @@ prompt.get(['Input a unique plugin application name'], function (err, result) { /** * Wrap code with immediately-invoked function expression - * @param code {String} the code to wrap. - * @returns {String} the wrapped code. - * @description + * ``` + * (function () { + * 'use strict'; * - * Wrapped code looks like: - ``` - (function () { - 'use strict'; - - // code goes here - - })(); - ``` + * // code goes here + * + * })(); + * ``` + * + * @param {string} code - the code to wrap. + * @returns {string} The wrapped code */ function wrapCodeAsIIFE(code) { if (Array.isArray(code)) { @@ -181,8 +183,9 @@ prompt.get(['Input a unique plugin application name'], function (err, result) { /** * Wrap a string with single quotes - * @param str {String} the string to wrap - * @returns {String} a new wrapped string + * + * @param {string} str - the string to wrap + * @returns {string} A single-quoted string */ function asString(str) { return ['\'', '\''].join(str); From ed6e8aa1b9c26c942cd44d14c97e2afb45a4756b Mon Sep 17 00:00:00 2001 From: Kelly Domico Date: Fri, 22 Jan 2016 15:01:48 -0800 Subject: [PATCH 3/8] Updated JS files with jsdocs --- src/app/api/api.module.js | 1 + src/app/api/apiManager.service.js | 3 +- src/app/app.module.js | 1 + src/app/event/event.module.js | 2 + src/app/event/event.service.js | 5 ++- src/app/model/account/account.model.js | 13 ++++++- src/app/model/model.module.js | 3 ++ src/app/model/modelManager.js | 19 ++++++++-- src/app/model/navigation/navigation.model.js | 23 +++++++----- src/app/view/application.directive.js | 37 +++++++++++++++++-- .../account-actions.directive.js | 31 ++++++++++++---- src/app/view/navbar/navbar.html | 2 +- .../navbar/navigation/navigation.directive.js | 23 ++++++++++-- src/app/view/view.module.js | 2 + tools/package.json | 1 + 15 files changed, 133 insertions(+), 33 deletions(-) diff --git a/src/app/api/api.module.js b/src/app/api/api.module.js index d923f66286..5a62c97678 100644 --- a/src/app/api/api.module.js +++ b/src/app/api/api.module.js @@ -5,6 +5,7 @@ * @namespace app.api * @memberof app * @name api + * @description The API layer of the UI platform that handles HTTP requests */ angular .module('app.api', [], config); diff --git a/src/app/api/apiManager.service.js b/src/app/api/apiManager.service.js index 4a9e810d6b..5502caeb05 100644 --- a/src/app/api/apiManager.service.js +++ b/src/app/api/apiManager.service.js @@ -8,8 +8,7 @@ /** * @memberof app.api * @name apiManager - * @description The API layer of the UI platform that handles - * HTTP requests + * @description The manager that handles registration and retrieval of APIs */ function apiManagerFactory() { var apis = {}; diff --git a/src/app/app.module.js b/src/app/app.module.js index db27015cc4..6dfc8806dc 100644 --- a/src/app/app.module.js +++ b/src/app/app.module.js @@ -3,6 +3,7 @@ /** * @namespace app + * @name app */ angular .module('app', [ diff --git a/src/app/event/event.module.js b/src/app/event/event.module.js index 9790a2b636..00f2a0409f 100644 --- a/src/app/event/event.module.js +++ b/src/app/event/event.module.js @@ -5,6 +5,8 @@ * @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', []); diff --git a/src/app/event/event.service.js b/src/app/event/event.service.js index aff349a780..e29c214d34 100644 --- a/src/app/event/event.service.js +++ b/src/app/event/event.service.js @@ -19,10 +19,11 @@ ]; /** + * @namespace app.event.eventService * @memberof app.event * @name eventService - * @description The event bus that allows communication between the - * view, model and API layers + * @description The event bus service + * @property {object} events - the default set of events (i.e. HTTP status codes) * @example * ``` * // subscribe to an event diff --git a/src/app/model/account/account.model.js b/src/app/model/account/account.model.js index 13cfb31db1..04a5712a94 100644 --- a/src/app/model/account/account.model.js +++ b/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; diff --git a/src/app/model/model.module.js b/src/app/model/model.module.js index 50cf48b59e..c53e2a180f 100644 --- a/src/app/model/model.module.js +++ b/src/app/model/model.module.js @@ -5,6 +5,9 @@ * @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', []); diff --git a/src/app/model/modelManager.js b/src/app/model/modelManager.js index 160601292c..d8123e6069 100644 --- a/src/app/model/modelManager.js +++ b/src/app/model/modelManager.js @@ -8,11 +8,10 @@ modelManagerFactory.$inject = []; /** + * @namespace app.model.modelManager * @memberof app.model - * @name modelManager - * @description The model layer of the UI platform that contains - * the business data objects and methods to retrieve/update the - * data + * @name app.model.modelManager + * @description The manager that handles registration and retrieval of models */ function modelManagerFactory() { var models = {}; @@ -23,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]; } diff --git a/src/app/model/navigation/navigation.model.js b/src/app/model/navigation/navigation.model.js index dc6bd126de..f265efef9d 100644 --- a/src/app/model/navigation/navigation.model.js +++ b/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); @@ -18,8 +24,9 @@ } /** - * @namespace Menu - * @name Menu + * @namespace app.model.navigation.Menu + * @memberof app.model.navigation + * @name app.model.navigation.Menu */ function Menu() {} @@ -28,16 +35,14 @@ angular.extend(Menu.prototype, { /** * @function addMenuItem - * @memberof Menu + * @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 {Menu} - * - * Each menu item has a sub-menu defined is `items`. + * @returns {app.model.navigation.Menu} */ addMenuItem: function (name, href, text, icon) { this.push({ @@ -45,16 +50,16 @@ href: href, text: text, icon: icon, - items: new Menu() + items: new Menu() // sub-menu }); return this; }, /** * @function reset - * @memberof Menu + * @memberof app.model.navigation.Menu * @description Clear the menu list - * @returns {Menu} + * @returns {app.model.navigation.Menu} */ reset: function () { this.length = 0; diff --git a/src/app/view/application.directive.js b/src/app/view/application.directive.js index 4aac110f5e..4270199b1b 100644 --- a/src/app/view/application.directive.js +++ b/src/app/view/application.directive.js @@ -9,32 +9,61 @@ 'app.basePath' ]; + /** + * @namespace app.view.application + * @memberof app.view + * @name application + * @property {app.view.application.ApplicationController} controller - the application controller + * @property {string} controllerAs - the application controller identifier + * @property {string} templateUrl - the application template filepath + */ function application(path) { return { - controller: Controller, + controller: ApplicationController, controllerAs: 'applicationCtrl', templateUrl: path + '/view/application.html' }; } - Controller.$inject = [ + ApplicationController.$inject = [ 'app.event.eventService', 'app.model.modelManager' ]; - function Controller(eventService, modelManager) { + /** + * @namespace app.view.ApplicationController + * @memberof app.view.application + * @name ApplicationController + * @param {app.event.eventService} eventService - the event bus service + * @param {app.model.modelManager} modelManager - the application model manager + * @property {app.event.eventService} eventService - the event bus service + * @property {app.model.account} account - the account model + * @property {app.model.navigation} navigation - the navigation model + */ + function ApplicationController(eventService, modelManager) { this.eventService = eventService; this.account = modelManager.retrieve('app.model.account'); this.navigation = modelManager.retrieve('app.model.navigation'); } - angular.extend(Controller.prototype, { + angular.extend(ApplicationController.prototype, { + /** + * @function login + * @memberof app.view.ApplicationController + * @description Log in to the application and emit the LOGGED_IN event + * @param {string} name - the username + */ login: function (name) { this.account.login(name); this.navigation.reset(); this.eventService.$emit(this.eventService.events.LOGGED_IN); }, + /** + * @function logout + * @memberof app.view.ApplicationController + * @description Log out of the application and emit the LOGGED_OUT event + */ logout: function () { this.account.logout(); this.navigation.reset(); diff --git a/src/app/view/navbar/account-actions/account-actions.directive.js b/src/app/view/navbar/account-actions/account-actions.directive.js index 5838c26876..cf83076a14 100644 --- a/src/app/view/navbar/account-actions/account-actions.directive.js +++ b/src/app/view/navbar/account-actions/account-actions.directive.js @@ -3,25 +3,42 @@ angular .module('app.view') - .directive('accountAction', accountAction); + .directive('accountActions', accountActions); - accountAction.$inject = [ + accountActions.$inject = [ 'app.basePath' ]; - function accountAction(path) { + /** + * @namespace app.view.accountActions + * @memberof app.view + * @name accountActions + * @description An account-actions UI component directive + * @param {string} path - the application base path + * @property {app.view.AccountActionsController} controller - the controller + * @property {string} controllerAs - the identifier for the controller + * @property {string} templateUrl - the template filepath + */ + function accountActions(path) { return { - controller: Controller, - controllerAs: 'accountActionCtrl', + controller: AccountActionsController, + controllerAs: 'accountActionsCtrl', templateUrl: path + '/view/navbar/account-actions/account-actions.html' }; } - Controller.$inject = [ + AccountActionsController.$inject = [ 'app.model.modelManager' ]; - function Controller(modelManager) { + /** + * @namespace app.view.AccountActionsController + * @memberof app.view + * @name AccountActionsController + * @param {app.model.modelManager} modelManager - the application model manager + * @property {app.model.account} account - the account model + */ + function AccountActionsController(modelManager) { this.account = modelManager.retrieve('app.model.account'); } diff --git a/src/app/view/navbar/navbar.html b/src/app/view/navbar/navbar.html index 1ff0afcb7a..412ae0ccab 100644 --- a/src/app/view/navbar/navbar.html +++ b/src/app/view/navbar/navbar.html @@ -24,7 +24,7 @@ translate> Sign in - + diff --git a/src/app/view/navbar/navigation/navigation.directive.js b/src/app/view/navbar/navigation/navigation.directive.js index 28f14b23de..2e6d2bd365 100644 --- a/src/app/view/navbar/navigation/navigation.directive.js +++ b/src/app/view/navbar/navigation/navigation.directive.js @@ -9,19 +9,36 @@ 'app.basePath' ]; + /** + * @namespace app.view.navigation + * @memberof app.view + * @name navigation + * @description A navigation UI component directive + * @param {string} path - the application base path + * @property {app.view.NavigationController} controller - the controller + * @property {string} controllerAs - the identifier for the controller + * @property {string} templateUrl - the template filepath + */ function navigation(path) { return { - controller: Controller, + controller: NavigationController, controllerAs: 'NavigationCtrl', templateUrl: path + '/view/navbar/navigation/navigation.html' }; } - Controller.$inject = [ + NavigationController.$inject = [ 'app.model.modelManager' ]; - function Controller(modelManager) { + /** + * @namespace app.view.NavigationController + * @memberof app.view + * @name NavigationController + * @param {app.model.modelManager} modelManager - the application model manager + * @property {app.model.navigation} menu - the navigation model + */ + function NavigationController(modelManager) { this.menu = modelManager.retrieve('app.model.navigation'); } diff --git a/src/app/view/view.module.js b/src/app/view/view.module.js index 128db328d6..7240d7fe5d 100644 --- a/src/app/view/view.module.js +++ b/src/app/view/view.module.js @@ -5,6 +5,8 @@ * @namespace app.view * @memberof app * @name view + * @description The view layer of the UI platform that contains + * the Angular directives and controllers */ angular .module('app.view', []); diff --git a/tools/package.json b/tools/package.json index da2f380d7c..79ef49539c 100644 --- a/tools/package.json +++ b/tools/package.json @@ -24,6 +24,7 @@ "gulp-eslint": "^1.1.1", "gulp-plumber": "^1.0.1", "jasmine-core": "^2.4.1", + "jsdoc": "^3.4.0", "karma": "^0.13.19", "karma-cli": "^0.1.2", "karma-coverage": "^0.5.3", From 3169c9a98b648a10a462b4550ba19cb538621f7c Mon Sep 17 00:00:00 2001 From: Kelly Domico Date: Fri, 22 Jan 2016 16:20:53 -0800 Subject: [PATCH 4/8] Updated jsdocs --- src/app/api/api.module.js | 13 ++++--- src/app/view/application.directive.js | 12 ++++--- src/app/view/console/console.directive.js | 7 ++++ src/app/view/landing/landing.directive.js | 7 ++++ src/app/view/navbar/navbar.directive.js | 7 ++++ src/config.js | 41 +++++++++++++---------- src/index.module.js | 4 +++ 7 files changed, 62 insertions(+), 29 deletions(-) diff --git a/src/app/api/api.module.js b/src/app/api/api.module.js index 5a62c97678..88bc43573f 100644 --- a/src/app/api/api.module.js +++ b/src/app/api/api.module.js @@ -18,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 diff --git a/src/app/view/application.directive.js b/src/app/view/application.directive.js index 4270199b1b..abd35d4f7f 100644 --- a/src/app/view/application.directive.js +++ b/src/app/view/application.directive.js @@ -31,7 +31,7 @@ ]; /** - * @namespace app.view.ApplicationController + * @namespace app.view.application.ApplicationController * @memberof app.view.application * @name ApplicationController * @param {app.event.eventService} eventService - the event bus service @@ -49,9 +49,10 @@ angular.extend(ApplicationController.prototype, { /** * @function login - * @memberof app.view.ApplicationController - * @description Log in to the application and emit the LOGGED_IN event + * @memberof app.view.application.ApplicationController + * @description Log in to the application * @param {string} name - the username + * @emits LOGGED_IN */ login: function (name) { this.account.login(name); @@ -61,8 +62,9 @@ /** * @function logout - * @memberof app.view.ApplicationController - * @description Log out of the application and emit the LOGGED_OUT event + * @memberof app.view.application.ApplicationController + * @description Log out of the application + * @emits LOGGED_OUT */ logout: function () { this.account.logout(); diff --git a/src/app/view/console/console.directive.js b/src/app/view/console/console.directive.js index 739a1f042d..4fa9d28f0b 100644 --- a/src/app/view/console/console.directive.js +++ b/src/app/view/console/console.directive.js @@ -9,6 +9,13 @@ 'app.basePath' ]; + /** + * @namespace app.view.console + * @memberof app.view + * @name console + * @description A console directive + * @property {string} templateUrl - the console template filepath + */ function console(path) { return { templateUrl: path + 'view/console/console.html' diff --git a/src/app/view/landing/landing.directive.js b/src/app/view/landing/landing.directive.js index 47789e7e8f..6dd2072827 100644 --- a/src/app/view/landing/landing.directive.js +++ b/src/app/view/landing/landing.directive.js @@ -9,6 +9,13 @@ 'app.basePath' ]; + /** + * @namespace app.view.landing + * @memberof app.view + * @name landing + * @description A landing page directive + * @property {string} templateUrl - the landing page template filepath + */ function landing(path) { return { templateUrl: path + 'view/landing/landing.html' diff --git a/src/app/view/navbar/navbar.directive.js b/src/app/view/navbar/navbar.directive.js index 226705ca59..a0d960087c 100644 --- a/src/app/view/navbar/navbar.directive.js +++ b/src/app/view/navbar/navbar.directive.js @@ -9,6 +9,13 @@ 'app.basePath' ]; + /** + * @namespace app.view.navbar + * @memberof app.view + * @name navbar + * @description A navbar directive + * @property {string} templateUrl - the navbar template filepath + */ function navbar(path) { return { templateUrl: path + '/view/navbar/navbar.html' diff --git a/src/config.js b/src/config.js index 892677ebdc..08ca55660e 100644 --- a/src/config.js +++ b/src/config.js @@ -3,6 +3,7 @@ /** * @namespace env + * @name env * @property {string} HELION_UI_FRAMEWORK_BASE_PATH - the Helion UI framework path */ var env = { @@ -17,28 +18,27 @@ }); /** + * @function registerApplication * @memberof env - * @name registerApplication * @description * Register a plugin application with the UI platform and include its * Angular module as a dependency of the UI platform module. * - * IMPORTANT: Every plugin application MUST include a `plugin.config.js` - * file at its root directory that will register itself with the UI platform. - * ``` - * env && env.registerApplication && env.env.registerApplication( - * 'My Application ID', - * 'my-application-angular-module-name', - * 'plugins/my-application/' - * ); - * ``` - * @param {string} id - the ID to identify the application being registered - * @param {string} angularModuleName - the unique Angular module name of the - * plugin application - * @param {string} basePath - the base path to the root folder where the - * plugin application resides or is installed. The basePath is relative to - * the 'src' folder. - */ + * IMPORTANT: Every plugin application MUST include a `plugin.config.js` + * file at its root directory that will register itself with the UI platform. + * @example + * env && env.registerApplication && env.env.registerApplication( + * 'My Application ID', + * 'my-application-angular-module-name', + * 'plugins/my-application/' + * ); + * @param {string} id - the ID to identify the application being registered + * @param {string} angularModuleName - the unique Angular module name of the + * plugin application + * @param {string} basePath - the base path to the root folder where the + * plugin application resides or is installed. The basePath is relative to + * the 'src' folder. + */ function registerApplication(id, angularModuleName, basePath) { env.plugins = env.plugins || {}; env.plugins[id] = { @@ -47,6 +47,13 @@ } } + /** + * @global + * @function gettext + * @description Returns the translated text + * @param {string} text - the text to be translated + * @returns {string} The translated text + */ function gettext(text) { return text; } diff --git a/src/index.module.js b/src/index.module.js index 5d716b6def..5467b55cb1 100644 --- a/src/index.module.js +++ b/src/index.module.js @@ -14,6 +14,10 @@ var pluginModules = _.chain(env.plugins).map('moduleName').value(); + /** + * @namespace green-box-console + * @name green-box-console + */ angular .module('green-box-console', ['app'].concat(angularModules, otherModules, pluginModules), config); From e917a7bcb0e775417e13b8de7eece49e40a86fe9 Mon Sep 17 00:00:00 2001 From: Kelly Domico Date: Fri, 22 Jan 2016 16:27:46 -0800 Subject: [PATCH 5/8] Updated @examples --- src/app/event/event.service.js | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/app/event/event.service.js b/src/app/event/event.service.js index e29c214d34..543eaf20ab 100644 --- a/src/app/event/event.service.js +++ b/src/app/event/event.service.js @@ -25,13 +25,11 @@ * @description The event bus service * @property {object} events - the default set of events (i.e. HTTP status codes) * @example - * ``` * // 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(); From 11031f25d1c6eebacb3028a1fe019070e62d5dd6 Mon Sep 17 00:00:00 2001 From: Kelly Domico Date: Fri, 22 Jan 2016 16:32:14 -0800 Subject: [PATCH 6/8] Added command to README --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index b85a82541d..e89fde0bcc 100644 --- a/README.md +++ b/README.md @@ -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 ``` \ No newline at end of file From 1e40cd10ac817c23c1a639154860de8fae60231b Mon Sep 17 00:00:00 2001 From: Kelly Domico Date: Mon, 25 Jan 2016 08:32:21 -0800 Subject: [PATCH 7/8] Updated .gitignore to ignore docs/src --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index b9ae1ee5dd..8c3444e8df 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,5 @@ npm-debug.log phantomjsdriver.log node_modules dist +docs/src lib From acc23ea20e83f7a248b5f9069efd8d9dd5f6f386 Mon Sep 17 00:00:00 2001 From: Kelly Domico Date: Mon, 25 Jan 2016 08:47:23 -0800 Subject: [PATCH 8/8] Updated README --- docs/README.md | 44 ++++++++++++++++++++++---------------------- tools/gulp.config.js | 2 ++ 2 files changed, 24 insertions(+), 22 deletions(-) diff --git a/docs/README.md b/docs/README.md index daa24f0185..0d5a608553 100644 --- a/docs/README.md +++ b/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 diff --git a/tools/gulp.config.js b/tools/gulp.config.js index 3b4f47cd80..dda56ce1a8 100644 --- a/tools/gulp.config.js +++ b/tools/gulp.config.js @@ -1,3 +1,5 @@ +'use strict'; + /** * This stores all the configuration information for Gulp */