[Persistence] Add comments

Add clarifying comments to persistence queue & failure handler.
WTD-1033.

platform/persistence/overwrite/src/PersistenceFailureHandler.js

@@ -6,29 +6,65 @@ define(
         "use strict";
 
         function PersistenceFailureHandler($q, dialogService, persistenceService) {
+            // Refresh revision information for the domain object associated
+            // with htis persistence failure
             function refresh(failure) {
-
+                // Perform a new read; this should update the persistence
+                // service's local revision records, so that the next request
+                // should permit the overwrite
+                return persistenceService.readObject(
+                    failure.persistence.getSpace(),
+                    failure.id,
+                    { cache: false } // Disallow caching
+                );
             }
 
+            // Issue a new persist call for the domain object associated with
+            // this failure.
+            function persist(failure) {
+                var undecoratedPersistence =
+                    failure.domainObject.getCapability('persistence');
+                return undecoratedPersistence &&
+                        undecoratedPersistence.persist();
+            }
+
+            // Retry persistence for this set of failed attempts
             function retry(failures) {
-
+                // Refresh all objects within the persistenceService to
+                // get up-to-date revision information; once complete,
+                // reissue the persistence request.
+                return $q.all(failures.map(refresh)).then(function () {
+                    return $q.all(failures.map(persist));
+                });
             }
 
+            // Handle failures in persistence
             function handleFailures(failures) {
+                // Prepare dialog for display
                 var dialogModel = new PersistenceFailureDialog(failures),
                     revisionErrors = dialogModel.model.revised;
 
+                // Handle user input (did they choose to overwrite?)
                 function handleChoice(key) {
+                    // If so, try again
                     if (key === PersistenceFailureConstants.OVERWRITE_KEY) {
                         return retry(revisionErrors);
                     }
                 }
 
+                // Prompt for user input, the overwrite if they said so.
                 return dialogService.getUserChoice(dialogModel)
                     .then(handleChoice);
             }
 
             return {
+                /**
+                 * Handle persistence failures by providing the user with a
+                 * dialog summarizing these failures, and giving the option
+                 * to overwrite/cancel as appropriate.
+                 * @param {Array} failures persistence failures, as prepared
+                 *        by PersistenceQueueHandler
+                 */
                 handle: handleFailures
             };
         }

platform/persistence/overwrite/src/QueuedPersistenceHandler.js

@@ -5,35 +5,55 @@ define(
     function () {
         "use strict";
 
-        function QueuedPersistenceHandler($q, failureHandler) {
+        /**
+         * Handles actual persistence invocations for queeud persistence
+         * attempts, in a group. Handling in a group in this manner
+         * also allows failure to be handled in a group (e.g. in a single
+         * summary dialog.)
+         * @param $q Angular's $q, for promises
+         * @param {PersistenceFailureHandler} handler to invoke in the event
+         *        that a persistence attempt fails.
+         */
+        function PersistenceQueueHandler($q, failureHandler) {
 
+            // Handle a group of persistence invocations
             function persistGroup(ids, queue, domainObjects) {
                 var failures = [];
 
+                // Try to persist a specific domain object
                 function tryPersist(id) {
+                    // Look up its persistence capability from the provided
+                    // id->persistence object.
                     var persistence = queue[id];
 
+                    // Handle success
                     function succeed(value) {
                         return value;
                     }
 
+                    // Handle failure (build up a list of failures)
                     function fail(error) {
                         failures.push({
                             id: id,
+                            persistence: persistence,
                             domainObject: domainObjects[id],
                             error: error
                         });
                         return false;
                     }
 
+                    // Invoke the actual persistence capability, then
+                    // note success or failures
                     return persistence.persist().then(succeed, fail);
                 }
 
+                // Handle any failures from the full operation
                 function handleFailure(value) {
                     return failures.length > 0 ?
                             failureHandler.handle(failures) : value;
                 }
 
+                // Try to persist everything, then handle any failures
                 return $q.all(ids.map(tryPersist)).then(handleFailure);
             }
 
@@ -54,6 +74,6 @@ define(
             };
         }
 
-        return QueuedPersistenceHandler;
+        return PersistenceQueueHandler;
     }
 );