[JSDoc] Add annotations

Bulk-add JSDoc annotations, WTD-1482.
This commit is contained in:
Victor Woeltjen
2015-08-07 11:44:54 -07:00
parent 14f97eae9c
commit c08a460d30
239 changed files with 939 additions and 185 deletions

View File

@ -31,6 +31,7 @@ define(
* actions for a given context, results from all
* services will be assembled and concatenated.
*
* @memberof platform/core
* @constructor
* @param {ActionProvider[]} actionProviders an array
* of action services
@ -65,6 +66,7 @@ define(
*
* @method
* @memberof ActionAggregator
* @memberof platform/core.ActionAggregator#
*/
getActions: getActions
};
@ -72,4 +74,4 @@ define(
return ActionAggregator;
}
);
);

View File

@ -45,6 +45,7 @@ define(
* which the action will be performed (also, the
* action which exposes the capability.)
*
* @memberof platform/core
* @constructor
*/
function ActionCapability($q, actionService, domainObject) {
@ -92,6 +93,7 @@ define(
* @returns {Promise} the result of the action that was
* performed, or undefined if no matching action
* was found.
* @memberof platform/core.ActionCapability#
*/
perform: performAction,
/**
@ -107,6 +109,7 @@ define(
* be taken as the "key" field to match against
* specific actions.
* @returns {Action[]} an array of matching actions
* @memberof platform/core.ActionCapability#
*/
getActions: getActions
};
@ -114,4 +117,4 @@ define(
return ActionCapability;
}
);
);

View File

@ -35,6 +35,7 @@ define(
* of actions exposed via extension (specifically, the "actions"
* category of extension.)
*
* @memberof platform/core
* @constructor
*/
function ActionProvider(actions) {
@ -145,6 +146,7 @@ define(
*
* @method
* @memberof ActionProvider
* @memberof platform/core.ActionProvider#
*/
getActions: getActions
};
@ -152,4 +154,4 @@ define(
return ActionProvider;
}
);
);

View File

@ -34,6 +34,7 @@ define(
* the actions it exposes always emit a log message when they are
* performed.
*
* @memberof platform/core
* @constructor
*/
function LoggingActionDecorator($log, actionService) {
@ -77,6 +78,7 @@ define(
*
* @method
* @memberof LoggingActionDecorator
* @memberof platform/core.LoggingActionDecorator#
*/
getActions: function () {
return actionService.getActions.apply(
@ -89,4 +91,4 @@ define(
return LoggingActionDecorator;
}
);
);

View File

@ -37,6 +37,7 @@ define(
* require consulting the object service (e.g. to trigger a database
* query to retrieve the nested object models.)
*
* @memberof platform/core
* @constructor
*/
function CompositionCapability($injector, domainObject) {
@ -94,6 +95,7 @@ define(
* Request the composition of this object.
* @returns {Promise.<DomainObject[]>} a list of all domain
* objects which compose this domain object.
* @memberof platform/core.CompositionCapability#
*/
invoke: promiseComposition
};
@ -112,4 +114,4 @@ define(
return CompositionCapability;
}
);
);

View File

@ -36,6 +36,7 @@ define(
* those whose `composition` capability was used to access this
* object.)
*
* @memberof platform/core
* @constructor
*/
function ContextCapability(parentObject, domainObject) {
@ -50,6 +51,7 @@ define(
*
* @returns {DomainObject} the immediate parent of this
* domain object.
* @memberof platform/core.ContextCapability#
*/
getParent: function () {
return parentObject;
@ -72,6 +74,7 @@ define(
* @returns {DomainObject[]} the full composition ancestry
* of the domain object which exposed this
* capability.
* @memberof platform/core.ContextCapability#
*/
getPath: function () {
var parentPath = [],
@ -95,6 +98,7 @@ define(
*
* @returns {DomainObject} the deepest ancestor of the domain
* object which exposed this capability.
* @memberof platform/core.ContextCapability#
*/
getRoot: function () {
var parentContext = parentObject &&
@ -109,4 +113,4 @@ define(
return ContextCapability;
}
);
);

View File

@ -42,6 +42,7 @@ define(
* @param {DomainObject} parentObject the domain object from which
* the wrapped object was retrieved
*
* @memberof platform/core
* @constructor
*/
function ContextualDomainObject(domainObject, parentObject) {
@ -63,4 +64,4 @@ define(
return ContextualDomainObject;
}
);
);

View File

@ -37,6 +37,7 @@ define(
* of constructor functions for capabilities, as
* exposed by extensions defined at the bundle level.
*
* @memberof platform/core
* @constructor
*/
function CoreCapabilityProvider(capabilities, $log) {
@ -84,6 +85,7 @@ define(
* @returns {Object.<string,function|Capability>} all
* capabilities known to be valid for this model, as
* key-value pairs
* @memberof platform/core.CoreCapabilityProvider#
*/
getCapabilities: getCapabilities
};
@ -92,3 +94,4 @@ define(
return CoreCapabilityProvider;
}
);

View File

@ -46,6 +46,7 @@ define(
* capabilities to be delegated.
*
* @param domainObject
* @memberof platform/core
* @constructor
*/
function DelegationCapability($q, domainObject) {
@ -96,6 +97,7 @@ define(
* @param {string} the name of the delegated capability
* @returns {DomainObject[]} the domain objects to which
* responsibility for this capability is delegated.
* @memberof platform/core.DelegationCapability#
*/
invoke: getDelegates,
/**
@ -105,6 +107,7 @@ define(
* @param {string} the name of the delegated capability
* @returns {DomainObject[]} the domain objects to which
* responsibility for this capability is delegated.
* @memberof platform/core.DelegationCapability#
*/
getDelegates: getDelegates,
doesDelegateCapability: doesDelegate
@ -115,4 +118,4 @@ define(
return DelegationCapability;
}
);
);

View File

@ -11,6 +11,8 @@ define(
* @property {string} name the human-readable name of this property
* @property {string} value the human-readable value of this property,
* for this specific domain object
* @constructor
* @memberof platform/core
*/
var TIME_FORMAT = "YYYY-MM-DD HH:mm:ss";
@ -82,6 +84,7 @@ define(
/**
* Get metadata about this object.
* @returns {MetadataProperty[]} metadata about this object
* @memberof platform/core.MetadataCapability#
*/
invoke: getMetadata
};
@ -90,3 +93,4 @@ define(
return MetadataCapability;
}
);

View File

@ -71,6 +71,7 @@ define(
*
* @param {DomainObject} domainObject the domain object
* which will expose this capability
* @memberof platform/core
* @constructor
*/
function MutationCapability(topic, now, domainObject) {
@ -118,6 +119,7 @@ define(
return {
/**
* Alias of `mutate`, used to support useCapability.
* @memberof platform/core.MutationCapability#
*/
invoke: mutate,
/**
@ -146,6 +148,7 @@ define(
* used)
* @returns {Promise.<boolean>} a promise for the result
* of the mutation; true if changes were made.
* @memberof platform/core.MutationCapability#
*/
mutate: mutate,
/**
@ -155,6 +158,7 @@ define(
* invoke the function returned by this method.
* @param {Function} listener function to call on mutation
* @returns {Function} a function to stop listening
* @memberof platform/core.MutationCapability#
*/
listen: listen
};
@ -163,3 +167,4 @@ define(
return MutationCapability;
}
);

View File

@ -40,6 +40,7 @@ define(
* @param {DomainObject} the domain object which shall expose
* this capability
*
* @memberof platform/core
* @constructor
*/
function PersistenceCapability(persistenceService, SPACE, domainObject) {
@ -80,6 +81,7 @@ define(
* @returns {Promise} a promise which will be resolved
* if persistence is successful, and rejected
* if not.
* @memberof platform/core.PersistenceCapability#
*/
persist: function () {
updatePersistenceTimestamp();
@ -94,6 +96,7 @@ define(
* persistence.
* @returns {Promise} a promise which will be resolved
* when the update is complete
* @memberof platform/core.PersistenceCapability#
*/
refresh: function () {
var model = domainObject.getModel();
@ -114,6 +117,7 @@ define(
*
* @returns {string} the name of the space which should
* be used to persist this object
* @memberof platform/core.PersistenceCapability#
*/
getSpace: function () {
return SPACE;
@ -123,4 +127,4 @@ define(
return PersistenceCapability;
}
);
);

View File

@ -38,6 +38,7 @@ define(
* which are not intended to appear in the tree, but are instead
* intended only for special, limited usage.
*
* @memberof platform/core
* @constructor
*/
function RelationshipCapability($injector, domainObject) {
@ -109,6 +110,7 @@ define(
* List all types of relationships exposed by this
* object.
* @returns {string[]} a list of all relationship types
* @memberof platform/core.RelationshipCapability#
*/
listRelationships: listRelationships,
/**
@ -118,6 +120,7 @@ define(
* @param {string} key the type of relationship
* @returns {Promise.<DomainObject[]>} a promise for related
* domain objects
* @memberof platform/core.RelationshipCapability#
*/
getRelatedObjects: promiseRelationships
};
@ -136,4 +139,4 @@ define(
return RelationshipCapability;
}
);
);

View File

@ -30,6 +30,7 @@ define(
* The caching model decorator maintains a cache of loaded domain
* object models, and ensures that duplicate models for the same
* object are not provided.
* @memberof platform/core
* @constructor
*/
function CachingModelDecorator(modelService) {
@ -114,6 +115,7 @@ define(
* containing key-value pairs, where keys are
* ids and values are models
* @method
* @memberof platform/core.CachingModelDecorator#
*/
getModels: function (ids) {
var neededIds = ids.filter(notCached);
@ -133,4 +135,4 @@ define(
return CachingModelDecorator;
}
);
);

View File

@ -30,6 +30,8 @@ define(
* Adds placeholder domain object models for any models which
* fail to load from the underlying model service.
* @implements {ModelService}
* @constructor
* @memberof platform/core
*/
function MissingModelDecorator(modelService) {
function missingModel(id) {
@ -57,3 +59,4 @@ define(
return MissingModelDecorator;
}
);

View File

@ -33,6 +33,7 @@ define(
* Allows multiple services which provide models for domain objects
* to be treated as one.
*
* @memberof platform/core
* @constructor
* @param {ModelProvider[]} providers the model providers to be
* aggregated
@ -77,6 +78,7 @@ define(
* containing key-value pairs,
* where keys are object identifiers and values
* are object models.
* @memberof platform/core.ModelAggregator#
*/
getModels: function (ids) {
return $q.all(providers.map(function (provider) {
@ -90,4 +92,4 @@ define(
return ModelAggregator;
}
);
);

View File

@ -33,6 +33,7 @@ define(
* A model service which reads domain object models from an external
* persistence service.
*
* @memberof platform/core
* @constructor
* @param {PersistenceService} persistenceService the service in which
* domain object models are persisted.
@ -83,6 +84,7 @@ define(
* containing key-value pairs,
* where keys are object identifiers and values
* are object models.
* @memberof platform/core.PersistedModelProvider#
*/
getModels: promiseModels
};
@ -91,4 +93,4 @@ define(
return PersistedModelProvider;
}
);
);

View File

@ -39,6 +39,7 @@ define(
* exposes them all as composition of the root object ROOT,
* whose model is also provided by this service.
*
* @memberof platform/core
* @constructor
*/
function RootModelProvider(roots, $q, $log) {
@ -68,6 +69,7 @@ define(
* containing key-value pairs,
* where keys are object identifiers and values
* are object models.
* @memberof platform/core.RootModelProvider#
*/
getModels: function (ids) {
return baseProvider.getModels(ids).then(addRoot);
@ -77,4 +79,4 @@ define(
return RootModelProvider;
}
);
);

View File

@ -31,6 +31,7 @@ define(
/**
* Loads static models, provided as declared extensions of bundles.
* @memberof platform/core
* @constructor
*/
function StaticModelProvider(models, $q, $log) {
@ -69,6 +70,7 @@ define(
* ids and values are models
* @method
* @memberof StaticModelProvider#
* @memberof platform/core.StaticModelProvider#
*/
getModels: function (ids) {
var result = {};
@ -82,4 +84,4 @@ define(
return StaticModelProvider;
}
);
);

View File

@ -37,6 +37,7 @@ define(
* @param {object} model the "JSONifiable" state of the object
* @param {Object.<string, Capability>|function} capabilities all
* capabilities to be exposed by this object
* @memberof platform/core
* @constructor
*/
function DomainObject(id, model, capabilities) {
@ -45,6 +46,7 @@ define(
* Get the unique identifier for this domain object.
* @return {string} the domain object's unique identifier
* @memberof DomainObject#
* @memberof platform/core.DomainObject#
*/
getId: function () {
return id;
@ -59,6 +61,7 @@ define(
*
* @return {object} the domain object's persistent state
* @memberof DomainObject#
* @memberof platform/core.DomainObject#
*/
getModel: function () {
return model;
@ -73,6 +76,7 @@ define(
* @return {Capability} the named capability, or undefined
* if not present.
* @memberof DomainObject#
* @memberof platform/core.DomainObject#
*/
getCapability: function (name) {
var capability = capabilities[name];
@ -87,6 +91,7 @@ define(
* @param {string} name the name of the capability to
* check for
* @returns {boolean} true if provided
* @memberof platform/core.DomainObject#
*/
hasCapability: function hasCapability(name) {
return this.getCapability(name) !== undefined;
@ -110,6 +115,7 @@ define(
* @param {...*} [arguments] to pass to the invocation
* @returns {*}
* @memberof DomainObject#
* @memberof platform/core.DomainObject#
*/
useCapability: function (name) {
// Get tail of args to pass to invoke
@ -125,4 +131,4 @@ define(
return DomainObject;
}
);
);

View File

@ -38,6 +38,7 @@ define(
* which provides capabilities (dynamic behavior)
* for domain objects.
* @param $q Angular's $q, for promise consolidation
* @memberof platform/core
* @constructor
*/
function DomainObjectProvider(modelService, capabilityService, $q) {
@ -97,6 +98,7 @@ define(
* are string identifiers for domain objects, and
* values are the corresponding domain objects themselves.
* @memberof module:core/object/object-provider.ObjectProvider#
* @memberof platform/core.DomainObjectProvider#
*/
getObjects: getObjects
};
@ -104,4 +106,4 @@ define(
return DomainObjectProvider;
}
);
);

View File

@ -31,12 +31,15 @@ define(
* `Date.now()` which can be injected to support testability.
*
* @returns {Function} a function which returns current system time
* @constructor
* @memberof platform/core
*/
function Now() {
/**
* Get the current time.
* @returns {number} current time, in milliseconds since
* 1970-01-01 00:00:00Z
* @memberof platform/core.Now#
*/
return function () {
return Date.now();
@ -45,4 +48,4 @@ define(
return Now;
}
);
);

View File

@ -42,6 +42,8 @@ define(
* resolve to the returned value of `fn` whenever that is invoked.
*
* @returns {Function}
* @constructor
* @memberof platform/core
*/
function Throttle($timeout) {
/**
@ -52,6 +54,7 @@ define(
* @param {boolean} apply true if a `$apply` call should be
* invoked after this function executes; defaults to
* `false`.
* @memberof platform/core.Throttle#
*/
return function (fn, delay, apply) {
var activeTimeout;
@ -82,3 +85,4 @@ define(
return Throttle;
}
);

View File

@ -44,6 +44,8 @@ define(
* arguments) are private; each call returns a new instance.
*
* @returns {Function}
* @constructor
* @memberof platform/core
*/
function Topic() {
var topics = {};
@ -71,6 +73,7 @@ define(
/**
* Use and (if necessary) create a new topic.
* @param {string} [key] name of the topic to use
* @memberof platform/core.Topic#
*/
return function (key) {
if (arguments.length < 1) {
@ -85,3 +88,4 @@ define(
return Topic;
}
);

View File

@ -64,6 +64,8 @@ define(
* @param b the second object to be merged
* @param merger the merger, as described above
* @returns {*} the result of merging `a` and `b`
* @constructor
* @memberof platform/core
*/
function mergeModels(a, b, merger) {
var mergeFunction;
@ -102,4 +104,4 @@ define(
return mergeModels;
}
);
);

View File

@ -34,6 +34,7 @@ define(
* type directly available when working with that object, by way
* of a `domainObject.getCapability('type')` invocation.
*
* @memberof platform/core
* @constructor
* @param {TypeService} typeService the service which
* provides type information
@ -51,4 +52,4 @@ define(
return TypeCapability;
}
);
);

View File

@ -42,6 +42,8 @@ define(
* key-value pairs describing a type and its
* relationship to other types.
* @memberof module:core/type/type-impl
* @constructor
* @memberof platform/core
*/
function TypeImpl(typeDef) {
var inheritList = typeDef.inherits || [],
@ -60,6 +62,7 @@ define(
*
* @returns {string} the key which identifies this type
* @memberof module:core/type/type-impl.TypeImpl#
* @memberof platform/core.TypeImpl#
*/
getKey: function () {
return typeDef.key;
@ -71,6 +74,7 @@ define(
*
* @returns {string} the human-readable name of this type
* @memberof module:core/type/type-impl.TypeImpl#
* @memberof platform/core.TypeImpl#
*/
getName: function () {
return typeDef.name;
@ -82,6 +86,7 @@ define(
*
* @returns {string} the human-readable description of this type
* @memberof module:core/type/type-impl.TypeImpl#
* @memberof platform/core.TypeImpl#
*/
getDescription: function () {
return typeDef.description;
@ -94,6 +99,7 @@ define(
*
* @returns {string} the glyph to be displayed
* @memberof module:core/type/type-impl.TypeImpl#
* @memberof platform/core.TypeImpl#
*/
getGlyph: function () {
return typeDef.glyph;
@ -105,6 +111,7 @@ define(
*
* @return {Array<TypeProperty>} properties associated with
* objects of this type
* @memberof platform/core.TypeImpl#
*/
getProperties: function () {
return (typeDef.properties || []).map(TypeProperty);
@ -114,6 +121,7 @@ define(
* this type.
*
* @return {object} initial domain object model
* @memberof platform/core.TypeImpl#
*/
getInitialModel: function () {
return typeDef.model || {};
@ -126,6 +134,7 @@ define(
*
* @returns {object} the raw definition for this type
* @memberof module:core/type/type-impl.TypeImpl#
* @memberof platform/core.TypeImpl#
*/
getDefinition: function () {
return typeDef;
@ -141,6 +150,7 @@ define(
* object, which this
* @returns {boolean} true
* @memberof module:core/type/type-impl.TypeImpl#
* @memberof platform/core.TypeImpl#
*/
instanceOf: function instanceOf(key) {
@ -162,6 +172,7 @@ define(
* the type definition's "feature" field.
* @param {string} feature a string identifying the feature
* @returns {boolean} true if the feature is supported
* @memberof platform/core.TypeImpl#
*/
hasFeature: function (feature) {
return featureSet[feature] || false;
@ -171,4 +182,4 @@ define(
return TypeImpl;
}
);
);

View File

@ -36,6 +36,7 @@ define(
* Instantiate a property associated with domain objects of a
* given type. This provides an interface by which
*
* @memberof platform/core
* @constructor
* @memberof module:core/type/type-property
*/
@ -114,6 +115,7 @@ define(
/**
* Retrieve the value associated with this property
* from a given model.
* @memberof platform/core.TypeProperty#
*/
getValue: function (model) {
var property = propertyDefinition.property ||
@ -133,6 +135,7 @@ define(
/**
* Set a value associated with this property in
* an object's model.
* @memberof platform/core.TypeProperty#
*/
setValue: function setValue(model, value) {
var property = propertyDefinition.property ||
@ -153,6 +156,7 @@ define(
},
/**
* Get the raw definition for this property.
* @memberof platform/core.TypeProperty#
*/
getDefinition: function () {
return propertyDefinition;
@ -162,4 +166,4 @@ define(
return TypeProperty;
}
);
);

View File

@ -62,6 +62,8 @@ define(
/**
* Look up an appropriate conversion between form values and model
* values, e.g. to numeric values.
* @constructor
* @memberof platform/core
*/
function TypePropertyConversion(name) {
if (name &&
@ -82,4 +84,4 @@ define(
return TypePropertyConversion;
}
);
);

View File

@ -55,6 +55,7 @@ define(
*
* @param {Array<TypeDefinition>} options.definitions the raw type
* definitions for this type.
* @memberof platform/core
* @constructor
* @memberof module:core/type/type-provider
*/
@ -154,6 +155,7 @@ define(
* promise for an array of all type instances defined
* by this service.
* @memberof module:core/type/type-provider.TypeProvider#
* @memberof platform/core.TypeProvider#
*/
listTypes: function () {
var self = this;
@ -176,6 +178,7 @@ define(
* @returns {Promise<module:core/type/type-impl.TypeImpl>} a
* promise for a type object identified by this key.
* @memberof module:core/type/type-provider.TypeProvider#
* @memberof platform/core.TypeProvider#
*/
getType: function (key) {
return new TypeImpl(lookupTypeDef(key));
@ -191,4 +194,4 @@ define(
}
);
);

View File

@ -35,6 +35,7 @@ define(
* thereabout) which are applicable to a specific domain
* object.
*
* @memberof platform/core
* @constructor
*/
function ViewCapability(viewService, domainObject) {
@ -44,6 +45,7 @@ define(
* this object.
* @returns {View[]} an array of view definitions
* which are applicable to this object.
* @memberof platform/core.ViewCapability#
*/
invoke: function () {
return viewService.getViews(domainObject);
@ -53,4 +55,4 @@ define(
return ViewCapability;
}
);
);

View File

@ -55,6 +55,7 @@ define(
* The role of a view provider and of a view capability is to
* describe what views are available, not how to instantiate them.
*
* @memberof platform/core
* @constructor
* @param {View[]} an array of view definitions
*/
@ -145,6 +146,7 @@ define(
* @param {DomainObject} domainObject the domain object to view
* @returns {View[]} all views which can be used to visualize
* this domain object.
* @memberof platform/core.ViewProvider#
*/
getViews: getViews
};
@ -152,4 +154,4 @@ define(
return ViewProvider;
}
);
);