From 95c3e1cdf47d7bcde7abb47f7fb1190456600d54 Mon Sep 17 00:00:00 2001 From: Victor Woeltjen Date: Thu, 20 Nov 2014 15:13:05 -0800 Subject: [PATCH] [Core] Add JSDoc, remove unused files Add JSDoc and remove unused files from type services and related files under the platform/core bundle. WTD-573. --- platform/core/src/types/MergeModels.js | 38 +++++- platform/core/src/types/TypeCapability.js | 16 ++- .../core/src/types/TypeCapabilityProvider.js | 113 ------------------ platform/core/src/types/TypeProvider.js | 20 +--- platform/core/src/types/TypeWizard.js | 70 ----------- .../test/types/TypeCapabilityProviderSpec.js | 13 -- 6 files changed, 51 insertions(+), 219 deletions(-) delete mode 100644 platform/core/src/types/TypeCapabilityProvider.js delete mode 100644 platform/core/src/types/TypeWizard.js delete mode 100644 platform/core/test/types/TypeCapabilityProviderSpec.js diff --git a/platform/core/src/types/MergeModels.js b/platform/core/src/types/MergeModels.js index f6b706ce54..d3475629e4 100644 --- a/platform/core/src/types/MergeModels.js +++ b/platform/core/src/types/MergeModels.js @@ -4,12 +4,46 @@ * Defines MergedModel, which allows a deep merge of domain object * models, or JSONifiable JavaScript objects generally. * - * @module core/model/merged-model */ define( function () { 'use strict'; + /** + * Utility function for merging domain object models (or any + * JavaScript object which follows the same conventions.) + * Performs a "deep merge", resolving conflicts (occurrences + * of the same property in both objects) such that: + * + * * Non-conflicting properties are both contained in the + * result object. + * * Conflicting properties which are both arrays are + * concatenated. + * * Conflicting properties which are both objects are + * merged recursively. + * * Conflicting properties which do not fall into any of the + * preceding categories are taken from the second argument, + * shadowing any values from the first. + * + * An optional third argument, the "merger", may be provided. + * This may be either a function, or an object containing + * key-value pairs where keys are strings (corresponding to + * the names of properties) and values are other mergers + * (either functions or objects.) + * + * * If the merger is a function, it will be used upon the + * two input objects in lieu of the behavior described + * above. + * * If the merger is an object, then its values will be + * used as mergers when resolving properties with + * corresponding keys in the recursive step. + * + * + * @param a the first object to be merged + * @param b the second object to be merged + * @param merger the merger, as described above + * @returns {*} the result of merging `a` and `b` + */ function mergeModels(a, b, merger) { var mergeFunction; @@ -37,7 +71,7 @@ define( return b; } - mergeFunction = merger && Function.isFunction(merger) ? merger : + mergeFunction = (merger && Function.isFunction(merger)) ? merger : (Array.isArray(a) && Array.isArray(b)) ? mergeArrays : (a instanceof Object && b instanceof Object) ? mergeObjects : mergeOther; diff --git a/platform/core/src/types/TypeCapability.js b/platform/core/src/types/TypeCapability.js index b507303a9d..e25028980b 100644 --- a/platform/core/src/types/TypeCapability.js +++ b/platform/core/src/types/TypeCapability.js @@ -9,17 +9,23 @@ define( "use strict"; /** + * The `type` capability makes information about a domain object's + * type directly available when working with that object, by way + * of a `domainObject.getCapability('type')` invocation. * * @constructor + * @param {TypeService} typeService the service which + * provides type information + * @param {DomainObject} domainObject the domain object + * which exposes the type capability */ function TypeCapability(typeService, domainObject) { var typeKey = domainObject.getModel().type, - type = typeService.getType(typeKey), - self = Object.create(type); + type = typeService.getType(typeKey); - self.invoke = function () { return self; }; - - return self; + // Simply return the type, but wrap with Object.create + // to avoid exposing the type object directly. + return Object.create(type); } return TypeCapability; diff --git a/platform/core/src/types/TypeCapabilityProvider.js b/platform/core/src/types/TypeCapabilityProvider.js deleted file mode 100644 index 4cc606d7d0..0000000000 --- a/platform/core/src/types/TypeCapabilityProvider.js +++ /dev/null @@ -1,113 +0,0 @@ -/*global define,Promise*/ - -/** - * Type capability provider. Provides capabilities for domain objects based - * on properties defined as part of their type, where type is inferred from - * a string with key "type" in the model. - * - * These capabilities include the "type" capability, which providers - * information about an object's type not stored in the model. - * - * @module core/type/type-capability-provider - */ -define( - [], - function () { - 'use strict'; - var promises = { - merge: Promise.all, - decorate: function (promise, callback) { - return promise.then(callback); - }, - as: function (value) { - return Promise.resolve(value); - } - }; - - /** - * Construct a new type capability provider. The provided type - * service will be used to obtain type information; the provided - * module service will be used to load modules which define - * factories for capabilities associated with types. - * - * @param {TypeService} typeService the service which will - * provide type information/definitions - * @param {ModuleService} moduleService the service which - * shall allow other JavaScript modules to be loaded. - * @constructor - * @memberof module:core/type/type-capability-provider - */ - function TypeCapabilityProvider(typeService, moduleService) { - var typeFactories = {}; - - function buildTypeFactory(type) { - var capabilities = type.getDefinition().capabilities || []; - - return promises.decorate( - promises.merge(capabilities.map(moduleService.get)), - function (modules) { - var factory = {}; - - modules.filter(function (mod) { - return mod; - }).forEach(function (mod) { - var capFactories = mod.capabilities || {}; - Object.keys(capFactories).forEach(function (k) { - factory[k] = capFactories[k]; - }); - }); - - // And the "type" capability - factory.type = function () { - return type; - }; - - return factory; - } - ); - } - - /** - * Description (TODO) - * @param {string} typeKey Description - * @returns {string} Description TODO - */ - function promiseTypeFactory(typeKey) { - return (typeFactories[typeKey] = typeFactories[typeKey] || promises.decorate( - typeService.getType(typeKey), - buildTypeFactory - )); - } - - return { - /** - * Get a capability which should be expressed by a domain - * object. This will return a promise for the capability instance; - * if the named capaability is not provided for that domain - * object by this service, the result of the fulfilled promise - * will be undefined. - * - * @param {module:core/api/domain-object.DomainObject} domainObject the - * domain object which may or may not express this capability - * @param {string} name the name of the capability requested - * @memberof module:core/type/type-capability-provider.TypeCapabilityProvider# - */ - getCapability: function (domainObject, name) { - var typeKey = domainObject.getModel().type; - return promises.decorate( - promiseTypeFactory(typeKey), - function (typeFactory) { - return typeFactory[name] ? - typeFactory[name](domainObject) : - undefined; - } - ); - } - }; - } - - return { - instantiate: TypeCapabilityProvider - }; - } -); \ No newline at end of file diff --git a/platform/core/src/types/TypeProvider.js b/platform/core/src/types/TypeProvider.js index 14b0b6f2cf..34718d72ed 100644 --- a/platform/core/src/types/TypeProvider.js +++ b/platform/core/src/types/TypeProvider.js @@ -1,24 +1,11 @@ -/*global define, Promise*/ +/*global define*/ -/** - * Provides information about types of domain objects within the running - * Open MCT Web instance. - * - * @module core/type/type-provider - */ define( ['./TypeImpl', './MergeModels'], function (TypeImpl, mergeModels) { 'use strict'; - var promises = { - merge: Promise.all, - decorate: function (promise, callback) { - return promise.then(callback); - }, - as: function (value) {return Promise.resolve(value); } - }, - TO_CONCAT = ['inherits', 'capabilities', 'properties', 'features'], + var TO_CONCAT = ['inherits', 'capabilities', 'properties', 'features'], TO_MERGE = ['model']; function copyKeys(a, b) { @@ -42,7 +29,8 @@ define( } /** - * Instantiate a new type provider. + * A type provider provides information about types of domain objects + * within the running Open MCT Web instance. * * @param {Array} options.definitions the raw type * definitions for this type. diff --git a/platform/core/src/types/TypeWizard.js b/platform/core/src/types/TypeWizard.js deleted file mode 100644 index 8953f48645..0000000000 --- a/platform/core/src/types/TypeWizard.js +++ /dev/null @@ -1,70 +0,0 @@ -/*global define*/ - -/** - * Default type wizard. Type wizards provide both a declarative - * description of the form which should be presented to a user - * when a new domain object of a given type is instantiatd, as - * well as the necessary functionality to convert this user input - * to a model for a domain object. - * - * This wizard is intended to be both a general-purpose default - * and a useful supertype; custom wizards for types which - * require additional information should use this as a base - * and append to the results of getSections(..) or add - * properties to the result of createModel(..) as appropriate - * to the more specific type. - * - * @module core/type/type-wizard - */ -define( - { - /** - * Get all sections appropriate to the display of this type. - * - * @returns {Array} - * @method - */ - getSections: function (typeKey) { - 'use strict'; - - return [ - { - label: "Title Options", - rows: [ - { - control: '_textfield', - label: "Title", - key: "name" - }, - { - control: '_checkbox', - label: "Display title by default", - key: "displayTitle" - } - ] - } - ]; - }, - - /** - * Create a model for a domain object based on user input. - * - * @param {object} formValue an object containing key-value - * pairs, where keys are properties indicated as part - * of a form's definition, and values are the result - * of user input. - * @return {object} the new model for a domain object - */ - createModel: function (formValue) { - 'use strict'; - - var model = { - type: formValue.type, - name: formValue.name, - display: { title: formValue.displayTitle } - }; - - return model; - } - } -); \ No newline at end of file diff --git a/platform/core/test/types/TypeCapabilityProviderSpec.js b/platform/core/test/types/TypeCapabilityProviderSpec.js deleted file mode 100644 index a351676657..0000000000 --- a/platform/core/test/types/TypeCapabilityProviderSpec.js +++ /dev/null @@ -1,13 +0,0 @@ -/*global define,describe,it,beforeEach,expect*/ - -define( - ['../../src/types/TypeCapabilityProvider'], - function () { - - 'use strict'; - - describe("Type capability provider", function () { - }); - - } -); \ No newline at end of file