[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

@@ -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(
+                $document.find('body').prepend($compile(TEMPLATE)(scope));
-                    $compile(
-                        "<mct-include ng-model=\"dialog\" key=\"'overlay-dialog'\"></mct-include>"
-                    )(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();