[Common UI] Add JSDoc for edit actions

Add in-line documentation for actions that are introduced
by the bundle platform/commonUI/edit, which introduces
Edit mode. One of the common user interface bundles being
transitioned for WTD-574.

platform/commonUI/edit/src/actions/CancelAction.js

@@ -1,14 +1,14 @@
 /*global define*/
 
-/**
- * The "Save" action; the action triggered by clicking Save from
- * Edit Mode. Exits the editing user interface and invokes object
- * capabilities to persist the changes that have been made.
- */
 define(
     function () {
         'use strict';
 
+        /**
+         * The "Cancel" action; the action triggered by clicking Cancel from
+         * Edit Mode. Exits the editing user interface and invokes object
+         * capabilities to persist the changes that have been made.
+         */
         function CancelAction($location, context) {
             var domainObject = context.domainObject;
 
@@ -33,6 +33,12 @@ define(
             }
 
             return {
+                /**
+                 * Cancel editing.
+                 *
+                 * @returns {Promise} a promise that will be fulfilled when
+                 *          cancellation has completed
+                 */
                 perform: function () {
                     return doCancel(getEditorCapability())
                         .then(returnToBrowse);
@@ -40,6 +46,12 @@ define(
             };
         }
 
+        /**
+         * Check if this action is applicable in a given context.
+         * This will ensure that a domain object is present in the context,
+         * and that this domain object is in Edit mode.
+         * @returns true if applicable
+         */
         CancelAction.appliesTo = function (context) {
             var domainObject = (context || {}).domainObject;
             return domainObject !== undefined &&

platform/commonUI/edit/src/actions/EditAction.js

@@ -8,6 +8,8 @@ define(
     function () {
         "use strict";
 
+        // A no-op action to return in the event that the action cannot
+        // be completed.
         var NULL_ACTION = {
             perform: function () {
                 return undefined;
@@ -15,12 +17,19 @@ define(
         };
 
         /**
-         *
+         * The Edit action is performed when the user wishes to enter Edit
+         * mode (typically triggered by the Edit button.) This will
+         * show the user interface for editing (by way of a change in
+         * route)
          * @constructor
          */
         function EditAction($location, navigationService, $log, context) {
             var domainObject = (context || {}).domainObject;
 
+            // We cannot enter Edit mode if we have no domain object to
+            // edit, so verify that one was defined as part of the
+            // context. (This is also verified in appliesTo, so this
+            // would indicate abnormal behavior.)
             if (!domainObject) {
                 $log.warn([
                     "No domain object to edit; ",
@@ -31,6 +40,9 @@ define(
             }
 
             return {
+                /**
+                 * Enter edit mode.
+                 */
                 perform: function () {
                     navigationService.setNavigation(domainObject);
                     $location.path("/edit");
@@ -38,6 +50,12 @@ define(
             };
         }
 
+        /**
+         * Check for applicability; verify that a domain object is present
+         * for this action to be performed upon.
+         * @param {ActionContext} context the context in which this action
+         *        will be performed; should contain a `domainObject` property
+         */
         EditAction.appliesTo = function (context) {
             return (context || {}).domainObject !== undefined;
         };

platform/commonUI/edit/src/actions/SaveAction.js

@@ -1,14 +1,15 @@
 /*global define*/
 
-/**
+
- * The "Save" action; the action triggered by clicking Save from
- * Edit Mode. Exits the editing user interface and invokes object
- * capabilities to persist the changes that have been made.
- */
 define(
     function () {
         'use strict';
 
+        /**
+         * The "Save" action; the action triggered by clicking Save from
+         * Edit Mode. Exits the editing user interface and invokes object
+         * capabilities to persist the changes that have been made.
+         */
         function SaveAction($location, context) {
             var domainObject = context.domainObject;
 
@@ -33,12 +34,24 @@ define(
             }
 
             return {
+                /**
+                 * Save changes and conclude editing.
+                 *
+                 * @returns {Promise} a promise that will be fulfilled when
+                 *          cancellation has completed
+                 */
                 perform: function () {
                     return doSave(getEditorCapability()).then(returnToBrowse);
                 }
             };
         }
 
+        /**
+         * Check if this action is applicable in a given context.
+         * This will ensure that a domain object is present in the context,
+         * and that this domain object is in Edit mode.
+         * @returns true if applicable
+         */
         SaveAction.appliesTo = function (context) {
             var domainObject = (context || {}).domainObject;
             return domainObject !== undefined &&