[Core] Add JSDoc for model components

Add JSDoc for components of modelService exposed
by platform/core. Part of ongoing preparation for
review and integration; WTD-573.

platform/core/bundle.json

@@ -31,7 +31,8 @@
             {
                 "provides": "modelService",
                 "type": "aggregator",
-                "implementation": "models/ModelAggregator.js"
+                "implementation": "models/ModelAggregator.js",
+                "depends": [ "$q" ]
             },
             {
                 "provides": "modelService",

platform/core/src/models/ModelAggregator.js

@@ -1,4 +1,4 @@
-/*global define,Promise*/
+/*global define*/
 
 /**
  * Module defining ModelAggregator. Created by vwoeltje on 11/7/14.
@@ -9,10 +9,17 @@ define(
         "use strict";
 
         /**
+         * Allows multiple services which provide models for domain objects
+         * to be treated as one.
          *
          * @constructor
+         * @param {ModelProvider[]} providers the model providers to be
+         *        aggregated
          */
-        function ModelAggregator(providers) {
+        function ModelAggregator($q, providers) {
+
+            // Merge results from multiple providers into one
+            // large result object.
             function mergeModels(provided, ids) {
                 var result = {};
                 ids.forEach(function (id) {
@@ -26,8 +33,24 @@ define(
             }
 
             return {
+                /**
+                 * Get models with the specified identifiers.
+                 *
+                 * This will invoke the `getModels()` method of all providers
+                 * given at constructor-time, and aggregate the result into
+                 * one object.
+                 *
+                 * Note that the returned object may contain a subset or a
+                 * superset of the models requested.
+                 *
+                 * @param {string[]} ids an array of domain object identifiers
+                 * @returns {Promise.<object>} a promise for  an object
+                 *          containing key-value pairs,
+                 *          where keys are object identifiers and values
+                 *          are object models.
+                 */
                 getModels: function (ids) {
-                    return Promise.all(providers.map(function (provider) {
+                    return $q.all(providers.map(function (provider) {
                         return provider.getModels(ids);
                     })).then(function (provided) {
                         return mergeModels(provided, ids);

platform/core/src/models/PersistedModelProvider.js

@@ -9,8 +9,15 @@ define(
         "use strict";
 
         /**
+         * A model service which reads domain object models from an external
+         * persistence service.
          *
          * @constructor
+         * @param {PersistenceService} persistenceService the service in which
+         *        domain object models are persisted.
+         * @param $q Angular's $q service, for working with promises
+         * @param {string} SPACE the name of the persistence space from which
+         *        models should be retrieved.
          */
         function PersistedModelProvider(persistenceService, $q, SPACE) {
             function promiseModels(ids) {
@@ -26,6 +33,22 @@ define(
             }
 
             return {
+                /**
+                 * Get models with the specified identifiers.
+                 *
+                 * This will invoke the underlying persistence service to
+                 * retrieve object models which match the provided
+                 * identifiers.
+                 *
+                 * Note that the returned object may contain a subset or a
+                 * superset of the models requested.
+                 *
+                 * @param {string[]} ids an array of domain object identifiers
+                 * @returns {Promise.<object>} a promise for  an object
+                 *          containing key-value pairs,
+                 *          where keys are object identifiers and values
+                 *          are object models.
+                 */
                 getModels: promiseModels
             };
         }

platform/core/src/models/RootModelProvider.js

@@ -9,16 +9,20 @@ define(
         "use strict";
 
         /**
+         * Provides the root object (id = "ROOT"), which is the top-level
+         * domain object shown when the application is started, from which all
+         * other domain objects are reached.
+         *
          * The root model provider works as the static model provider,
          * except that it aggregates roots[] instead of models[], and
-         * exposes them all as composition of the root object ROOT.
+         * exposes them all as composition of the root object ROOT,
+         * whose model is also provided by this service.
          *
          * @constructor
          */
         function RootModelProvider(roots, $log) {
-            var ids = roots.map(function (root) {
+            // Pull out identifiers to used as ROOT's
-                    return root.id;
+            var ids = roots.map(function (root) { return root.id; }),
-                }),
                 baseProvider = new StaticModelProvider(roots, $log);
 
             function addRoot(models) {
@@ -30,7 +34,20 @@ define(
             }
 
             return {
-                getModels: function(ids) {
+
+                /**
+                 * Get models with the specified identifiers.
+                 *
+                 * Note that the returned object may contain a subset or a
+                 * superset of the models requested.
+                 *
+                 * @param {string[]} ids an array of domain object identifiers
+                 * @returns {Promise.<object>} a promise for  an object
+                 *          containing key-value pairs,
+                 *          where keys are object identifiers and values
+                 *          are object models.
+                 */
+                getModels: function (ids) {
                     return baseProvider.getModels(ids).then(addRoot);
                 }
             };