From 5a437a712470ffd1d6906250970528e72ce8acd6 Mon Sep 17 00:00:00 2001
From: Victor Woeltjen <victor.woeltjen@nasa.gov>
Date: Thu, 20 Nov 2014 13:37:37 -0800
Subject: [PATCH] [Core] Add JSDoc for action service components

Add JSDoc for remaining action service components
(ActionProvider and LoggingActionDecorator) to
satisfy code standards in the platform/core bundle,
for WTD-573.
---
 platform/core/src/actions/ActionProvider.js   | 36 +++++++++++++++++++
 .../src/actions/LoggingActionDecorator.js     | 24 +++++++++++++
 2 files changed, 60 insertions(+)

diff --git a/platform/core/src/actions/ActionProvider.js b/platform/core/src/actions/ActionProvider.js
index 4d8821bd05..9441492964 100644
--- a/platform/core/src/actions/ActionProvider.js
+++ b/platform/core/src/actions/ActionProvider.js
@@ -9,6 +9,10 @@ define(
         "use strict";
 
         /**
+         * An ActionProvider (implementing ActionService) provides actions
+         * that are applicable in specific contexts, chosen from a set
+         * of actions exposed via extension (specifically, the "actions"
+         * category of extension.)
          *
          * @constructor
          */
@@ -16,6 +20,10 @@ define(
             var actionsByKey = {},
                 actionsByCategory = {};
 
+            // Instantiate an action; invokes the constructor and
+            // additionally fills in the action's getMetadata method
+            // with the extension definition (if no getMetadata
+            // method was supplied.)
             function instantiateAction(Action, context) {
                 var action = new Action(context),
                     metadata;
@@ -34,6 +42,10 @@ define(
                 return action;
             }
 
+            // Filter the array of actions down to those which are
+            // applicable in a given context, according to the static
+            // appliesTo method of given actions (if defined), and
+            // instantiate those applicable actions.
             function createIfApplicable(actions, context) {
                 return (actions || []).filter(function (Action) {
                     return Action.appliesTo ?
@@ -43,12 +55,15 @@ define(
                 });
             }
 
+            // Get an array of actions that are valid in the supplied context.
             function getActions(actionContext) {
                 var context = (actionContext || {}),
                     category = context.category,
                     key = context.key,
                     candidates;
 
+                // Match actions to the provided context by comparing "key"
+                // and/or "category" parameters, if specified.
                 candidates = actions;
                 if (key) {
                     candidates = actionsByKey[key];
@@ -61,6 +76,9 @@ define(
                     candidates = actionsByCategory[category];
                 }
 
+                // Instantiate those remaining actions, with additional
+                // filtering per any appliesTo methods defined on those
+                // actions.
                 return createIfApplicable(candidates, context);
             }
 
@@ -79,6 +97,24 @@ define(
             });
 
             return {
+                /**
+                 * Get a list of actions which are valid in a given
+                 * context.
+                 *
+                 * @param {ActionContext} the context in which
+                 *        the action will occur; this is a
+                 *        JavaScript object containing key-value
+                 *        pairs. Typically, this will contain a
+                 *        field "domainObject" which refers to
+                 *        the domain object that will be acted
+                 *        upon, but may contain arbitrary information
+                 *        recognized by specific providers.
+                 * @return {Action[]} an array of actions which
+                 *        may be performed in the provided context.
+                 *
+                 * @method
+                 * @memberof ActionProvider
+                 */
                 getActions: getActions
             };
         }
diff --git a/platform/core/src/actions/LoggingActionDecorator.js b/platform/core/src/actions/LoggingActionDecorator.js
index 4f3da0af89..d4b1281715 100644
--- a/platform/core/src/actions/LoggingActionDecorator.js
+++ b/platform/core/src/actions/LoggingActionDecorator.js
@@ -9,10 +9,15 @@ define(
         "use strict";
 
         /**
+         * The LoggingActionDecorator decorates an ActionService such that
+         * the actions it exposes always emit a log message when they are
+         * performed.
          *
          * @constructor
          */
         function LoggingActionDecorator($log, actionService) {
+            // Decorate the perform method of the specified action, such that
+            // it emits a log message whenever performed.
             function addLogging(action) {
                 var logAction = Object.create(action),
                     domainObject =
@@ -32,6 +37,25 @@ define(
             }
 
             return {
+                /**
+                 * Get a list of actions which are valid in a given
+                 * context. These actions will additionally log
+                 * themselves when performed.
+                 *
+                 * @param {ActionContext} the context in which
+                 *        the action will occur; this is a
+                 *        JavaScript object containing key-value
+                 *        pairs. Typically, this will contain a
+                 *        field "domainObject" which refers to
+                 *        the domain object that will be acted
+                 *        upon, but may contain arbitrary information
+                 *        recognized by specific providers.
+                 * @return {Action[]} an array of actions which
+                 *        may be performed in the provided context.
+                 *
+                 * @method
+                 * @memberof LoggingActionDecorator
+                 */
                 getActions: function () {
                     return actionService.getActions.apply(
                         actionService,