[Core] Add JSDoc for capabilities

Add JSDoc for remaining core capabilities, to meet
code standards for integration. WTD-573.

platform/core/src/capabilities/CoreCapabilityProvider.js

@@ -9,7 +9,13 @@ define(
         "use strict";
 
         /**
-         * Provides capabilities based on extension definitions.
+         * Provides capabilities based on extension definitions,
+         * matched to domain object models.
+         *
+         * @param {Array.<function(DomainObject) : Capability>} an array
+         *        of constructor functions for capabilities, as
+         *        exposed by extensions defined at the bundle level.
+         *
          * @constructor
          */
         function CoreCapabilityProvider(capabilities) {

platform/core/src/capabilities/DelegationCapability.js

@@ -8,6 +8,25 @@ define(
     function () {
         'use strict';
 
+
+        /**
+         * The `delegation` capability allows a domain object to indicate
+         * that it wishes to delegate responsibility for some other
+         * capability to some other domain objects.
+         *
+         * This is specifically useful in the case of telemetry panels,
+         * which delegate responsibility for the `telemetry` capability
+         * to their contained objects.
+         *
+         * A type of domain object may indicate that it wishes to delegate
+         * responsibility for one or more capabilities to the members of
+         * its composition; this is done by included a `delegates` field
+         * in the type's definition, which contains an array of names of
+         * capabilities to be delegated.
+         *
+         * @param domainObject
+         * @constructor
+         */
         function DelegationCapability(domainObject) {
             var delegateCapabilities = {},
                 type = domainObject.getCapability("type");
@@ -44,7 +63,28 @@ define(
             }
 
             return {
+                /**
+                 * Invoke this capability; alias of `getDelegates`, used to
+                 * simplify usage, e.g.:
+                 *
+                 * `domainObject.useCapability("delegation", "telemetry")`
+                 *
+                 * ...will retrieve all members of a domain object's
+                 * composition which have a "telemetry" capability.
+                 *
+                 * @param {string} the name of the delegated capability
+                 * @returns {DomainObject[]} the domain objects to which
+                 *          responsibility for this capability is delegated.
+                 */
                 invoke: getDelegates,
+                /**
+                 * Get the domain objects which are intended to be delegated
+                 * responsibility for some specific capability.
+                 *
+                 * @param {string} the name of the delegated capability
+                 * @returns {DomainObject[]} the domain objects to which
+                 *          responsibility for this capability is delegated.
+                 */
                 getDelegates: getDelegates,
                 doesDelegateCapability: doesDelegate
             };

platform/core/src/capabilities/MutationCapability.js

@@ -21,6 +21,26 @@ define(
             });
         }
 
+        /**
+         * The `mutation` capability allows a domain object's model to be
+         * modified. Wrapping such modifications in calls made through
+         * this capability allows these changes to be tracked (e.g. to
+         * ensure that a domain object's `modified` timestamp is kept
+         * up-to-date.)
+         *
+         * Usage:
+         *
+         * ```
+         * domainObject.useCapability("mutation", function (model) {
+         *     // make changes to model here...
+         * });
+         * ```
+         *
+         * @param $q Angular's $q service, for promises
+         * @param {DomainObject} domainObject the domain object
+         *        which will expose this capability
+         * @constructor
+         */
         function MutationCapability($q, domainObject) {
 
             function mutate(mutator) {
@@ -54,7 +74,35 @@ define(
             }
 
             return {
-                invoke: mutate
+                /**
+                 * Alias of `mutate`, used to support useCapability.
+                 */
+                invoke: mutate,
+                /**
+                 * Modify the domain object's model, using a provided
+                 * function. This function will receive a copy of the
+                 * domain object's model as an argument; behavior
+                 * varies depending on that function's return value:
+                 *
+                 * * If no value (or undefined) is returned by the mutator,
+                 *   the state of the model object delivered as the mutator's
+                 *   argument will become the domain object's new model.
+                 *   This is useful for writing code that modifies the model
+                 *   directly.
+                 * * If a plain object is returned, that object will be used
+                 *   as the domain object's new model.
+                 * * If boolean `false` is returned, the mutation will be
+                 *   cancelled.
+                 * * If a promise is returned, its resolved value will be
+                 *   handled as one of the above.
+                 *
+                 *
+                 * @params {function} mutator the function which will make
+                 *         changes to the domain object's model.
+                 * @returns {Promise.<boolean>} a promise for the result
+                 *         of the mutation; true if changes were made.
+                 */
+                mutate: mutate
             };
         }