From 6cce00d6012b28d6afc0f46cdabe44d24ee2c908 Mon Sep 17 00:00:00 2001
From: Victor Woeltjen <victor.woeltjen@nasa.gov>
Date: Tue, 25 Nov 2014 13:31:30 -0800
Subject: [PATCH] [Common UI] Add JSDoc to DialogService

Add in-line documentation to the dialog service,
exposed by bundle platform/commonUI/dialog, one
of the common user interface bundles being
transitioned for WTD-574.
---
 platform/commonUI/dialog/src/DialogService.js | 30 +++++++++++++++----
 1 file changed, 24 insertions(+), 6 deletions(-)

diff --git a/platform/commonUI/dialog/src/DialogService.js b/platform/commonUI/dialog/src/DialogService.js
index 954c2d40cb..2157e0d00b 100644
--- a/platform/commonUI/dialog/src/DialogService.js
+++ b/platform/commonUI/dialog/src/DialogService.js
@@ -8,28 +8,46 @@ define(
     function () {
         "use strict";
 
+        // Template to inject into the DOM to show the dialog; really just points to
+        // the overlay-dialog template.
+        var TEMPLATE = "<mct-include ng-model=\"dialog\" key=\"'overlay-dialog'\"></mct-include>";
+
         /**
-         *
+         * The dialog service is responsible for handling window-modal
+         * communication with the user, such as displaying forms for user
+         * input.
          * @constructor
          */
         function DialogService($document, $compile, $rootScope, $timeout, $q, $log) {
             var scope;
 
+            // Inject the dialog at the top of the body; this is necessary to
+            // ensure that the dialog is positioned appropriately and can fill
+            // the screen to block other interactions.
             function addContent() {
                 scope = $rootScope.$new();
-                $document.find('body').prepend(
-                    $compile(
-                        "<mct-include ng-model=\"dialog\" key=\"'overlay-dialog'\"></mct-include>"
-                    )(scope)
-                );
+                $document.find('body').prepend($compile(TEMPLATE)(scope));
                 scope.dialog = { visible: false, value: {} };
             }
 
+            // Dismiss the dialog; just stop showing it, and release any
+            // form information for garbage collection.
             function dismiss() {
                 scope.dialog = { visible: false, value: {} };
             }
 
             return {
+                /**
+                 * Request user input via a window-modal dialog.
+                 *
+                 * @param {FormModel} formModel a description of the form
+                 *        to be shown (see platform/forms)
+                 * @param {object} value the initial state of the form
+                 * @returns {Promise} a promsie for the form value that the
+                 *          user has supplied; this may be rejected if
+                 *          user input cannot be obtained (for instance,
+                 *          because the user cancelled the dialog)
+                 */
                 getUserInput: function (formModel, value) {
                     var deferred = $q.defer();