[Core] Add comments to ActionCapability

Add JSDoc comments to ActionCapability to satisfy
code standards in the platform/core bundle, for
WTD-573.

platform/core/bundle.json

@@ -111,7 +111,7 @@
             {
                 "key": "action",
                 "implementation": "actions/ActionCapability.js",
-                "depends": [ "actionService" ]
+                "depends": [ "$q", "actionService" ]
             },
             {
                 "key": "view",

platform/core/src/actions/ActionCapability.js

@@ -9,12 +9,28 @@ define(
         "use strict";
 
         /**
+         * The ActionCapability allows applicable Actions to be retrieved and
+         * performed for specific domain objects, e.g.:
+         *
+         * `domainObject.getCapability("action").perform("navigate");`
+         *
+         * ...will initiate a navigate action upon the domain object,
+         * if an action with key "navigate" is defined.
+         *
+         * @param {*} $q Angular's $q service, for promises
+         * @param {ActionService} actionService the service from
+         *        which to retrieve actions.
+         * @param {DomainObject} domainObject the object upon
+         *        which the action will be performed (also, the
+         *        action which exposes the capability.)
          *
          * @constructor
          */
-        function ActionCapability(actionService, domainObject) {
+        function ActionCapability($q, actionService, domainObject) {
-            var self;
 
+            // Get all actions which are valid in this context;
+            // this simply redirects to the action service,
+            // but additionally adds a domainObject field.
             function getActions(context) {
                 var baseContext = typeof context === 'string' ?
                         { key: context } :
@@ -26,26 +42,53 @@ define(
                 return actionService.getActions(actionContext);
             }
 
+            // Alias to getActions(context)[0].perform, with a
+            // check for empty arrays.
             function performAction(context) {
                 var actions = getActions(context);
 
-                return Promise.resolve(
+                return $q.when(
                     (actions && actions.length > 0) ?
                             actions[0].perform() :
                             undefined
                 );
             }
 
-            self = {
+            return {
-                invoke: function () {
+                /**
-                    return self;
+                 * Perform an action. This will find and perform the
-                },
+                 * first matching action available for the specified
+                 * context or key.
+                 *
+                 * @param {ActionContext|string} context the context in which
+                 *       to perform the action; this is passed along to
+                 *       the action service to match against available
+                 *       actions. The "domainObject" field will automatically
+                 *       be populated with the domain object that exposed
+                 *       this capability. If given as a string, this will
+                 *       be taken as the "key" field to match against
+                 *       specific actions.
+                 * @returns {Promise} the result of the action that was
+                 *       performed, or undefined if no matching action
+                 *       was found.
+                 */
                 perform: performAction,
+                /**
+                 * Get actions which are available for this domain object,
+                 * in this context.
+                 *
+                 * @param {ActionContext|string} context the context in which
+                 *       to perform the action; this is passed along to
+                 *       the action service to match against available
+                 *       actions. The "domainObject" field will automatically
+                 *       be populated with the domain object that exposed
+                 *       this capability. If given as a string, this will
+                 *       be taken as the "key" field to match against
+                 *       specific actions.
+                 * @returns {Action[]} an array of matching actions
+                 */
                 getActions: getActions
-
             };
-
-            return self;
         }
 
         return ActionCapability;